i

Codename One Developer Guide

Version 3.4, Aug 01 2016

Table of Contents
................................................................................................................................. xv
About This Guide .................................................................................................... xvi
1. Introduction ............................................................................................................ 1
1.1. How Does Codename One Work? ............................................................. 1
1.1.1. Why Build Servers? .......................................................................... 2
1.1.2. Versions In Codename One ............................................................. 5
1.2. History ......................................................................................................... 6
1.3. Installation ................................................................................................... 7
1.3.1. Installing Codename One In NetBeans ............................................. 7
1.3.2. Installing Codename One In Eclipse ................................................. 9
1.3.3. Installing Codename One In IntelliJ IDEA ....................................... 11
1.4. Hello World Application ............................................................................. 12
1.4.1. The Source Code Of The Hello World App ..................................... 16
1.4.2. Building & Deploying On Devices ................................................... 27
1.5. Application Lifecycle .................................................................................. 30
1.5.1. Suspend/Resume ............................................................................ 31
2. Basics: Themes, Styles, Components & Layouts ................................................ 32
2.1. What Is A Theme, What Is A Style & What Is a Component? ................... 32
2.2. Native Theme ............................................................................................ 33
2.3. Component/Container Hierarchy ............................................................... 37
2.4. Layout Managers ...................................................................................... 38
2.4.1. Constraint Based Layout Managers ................................................ 39
2.4.2. Understanding Preferred Size ......................................................... 40
2.4.3. Flow Layout ..................................................................................... 42
2.4.4. Box Layout ...................................................................................... 47
2.4.5. Border Layout ................................................................................. 51
2.4.6. Grid Layout .....................................................................................
2.4.7. Table Layout ...................................................................................
2.4.8. Layered Layout ...............................................................................
2.4.9. GridBag Layout ...............................................................................
2.4.10. Group Layout ................................................................................
2.4.11. Mig Layout ....................................................................................
2.5. GUI Builder ...............................................................................................
2.5.1. Hello World .....................................................................................
3. Theme Basics .....................................................................................................
3.1. Understanding Codename One Themes ...................................................

iii

53
57
62
65
67
71
73
75
94
94

Codename One Developer Guide

3.2. Customizing Your Theme .......................................................................... 95
3.3. Customizing The Title ............................................................................. 100
3.3.1.
3.3.2.
3.3.3.
3.3.4.
3.3.5.

Background Priorities & Types ......................................................

The Background Behavior & Image ..............................................
The Color Settings ........................................................................
Alignment ......................................................................................
Padding & Margin .........................................................................

101
102
112
113
113

3.3.6. Borders ..........................................................................................

3.3.7. 9-Piece Image Border ...................................................................
3.3.8. Horizontal/Vertical Image Border ..................................................
3.3.9. Empty Border ................................................................................
3.3.10. Bevel/Etched Borders .................................................................
3.3.11. Derive ..........................................................................................
3.3.12. Fonts ...........................................................................................
4. Advanced Theming ...........................................................................................
4.1. Working With UIIDs ................................................................................
4.2. Theme Layering ......................................................................................
4.3. Override Resources In Platform ..............................................................
4.4. Theme Constants ....................................................................................
4.5. Native Theming .......................................................................................
4.6. How Does A theme Work? .....................................................................
4.7. Understanding Images & Multi-Images ...................................................
4.8. Use Millimeters for Padding/Margin & Font Sizes ...................................
4.8.1. Fractions of Millimeters .................................................................
4.9. Converting a PSD To A Theme ..............................................................
4.9.1. Breaking Down the PSD ...............................................................
4.9.2. The Code ......................................................................................
4.9.3. Styling The UI ...............................................................................
5. The Components Of Codename One ...............................................................
5.1. Container .................................................................................................
5.1.1. Composite Components ................................................................
5.2. Form ........................................................................................................
5.3. Dialog ......................................................................................................
5.3.1. Styling Dialogs ..............................................................................
5.3.2. Tint & Blurring ...............................................................................
5.3.3. Popup Dialog ................................................................................
5.4. InteractionDialog ......................................................................................
5.5. Label ........................................................................................................

115
115
121
122
122
122
124
132
132
132
133
135
147
148
150
153
153
154
158
168
171
176
176
176
178
180
184
184
189
191
194

iv

Codename One Developer Guide

5.6. TextField & TextArea .............................................................................. 196
5.6.1. Masking ......................................................................................... 198
5.6.2. The Virtual Keyboard ....................................................................
5.7. Button ......................................................................................................
5.8. CheckBox/RadioButton ...........................................................................
5.8.1. Toggle Button ................................................................................
5.9. ComponentGroup ....................................................................................

199
201
203
204
208

5.10. MultiButton .............................................................................................

5.10.1. Styling The MultiButton ...............................................................
5.11. SpanButton ............................................................................................
5.12. SpanLabel .............................................................................................
5.13. OnOffSwitch ..........................................................................................
5.13.1. Validation .....................................................................................
5.14. InfiniteProgress ......................................................................................
5.15. InfiniteScrollAdapter & InfiniteContainer ................................................
5.15.1. The InfiniteContainer ...................................................................
5.16. List, MultiList, Renderers & Models ......................................................
5.16.1. InfiniteContainer/InfiniteScrollAdapter vs. List/ContainerList .......
5.16.2. Why Isnt List Deprecated? .........................................................
5.16.3. MVC In Lists ...............................................................................
5.16.4. Understanding MVC ....................................................................
5.16.5. Important - Lists & Layout Managers ..........................................
5.16.6. MultiList & DefaultListModel ........................................................
5.16.7. List Cell Renderer .......................................................................
5.16.8. Generic List Cell Renderer .........................................................
5.16.9. ComboBox ...................................................................................
5.17. Slider .....................................................................................................
5.18. Table .....................................................................................................
5.19. Tree .......................................................................................................
5.20. ShareButton ...........................................................................................
5.21. Tabs ......................................................................................................
5.22. MediaManager & MediaPlayer ..............................................................
5.23. ImageViewer ..........................................................................................
5.24. ScaleImageLabel & ScaleImageButton .................................................
5.25. Toolbar ..................................................................................................
5.25.1. Search Mode ...............................................................................
5.25.2. Title Animations ...........................................................................
5.26. BrowserComponent & WebBrowser ......................................................

211
213
214
214
216
218
219
221
225
226
226
226
227
228
231
231
237
240
246
247
249
259
263
266
271
275
282
283
289
291
297

Codename One Developer Guide

5.26.1. BrowserComponent Hierarchy .................................................... 299
5.26.2. NavigationCallback ...................................................................... 300
5.26.3. JavaScript ....................................................................................
5.26.4. Cordova/PhoneGap Integration ...................................................
5.27. AutoCompleteTextField .........................................................................
5.28. Picker ....................................................................................................
5.29. SwipeableContainer ..............................................................................

302
306
307
310
317

5.30. EmbeddedContainer ..............................................................................

5.31. MapComponent .....................................................................................
5.32. Chart Component ..................................................................................
5.32.1. Device Support ...........................................................................
5.32.2. Features ......................................................................................
5.32.3. Chart Types ................................................................................
5.32.4. How to Create A Chart ...............................................................
5.33. Calendar ................................................................................................
5.34. ToastBar ................................................................................................
5.35. SignatureComponent .............................................................................
5.36. Accordion ..............................................................................................
5.37. Floating Hint ..........................................................................................
6. Animations & Transitions ..................................................................................
6.1. Layout Reflow .........................................................................................
6.2. Layout Animations ...................................................................................
6.2.1. Unlayout Animations .....................................................................
6.2.2. Hiding & Visibility ..........................................................................
6.2.3. Synchronicity In Animations ..........................................................
6.2.4. Sequencing Animations Via AnimationManager ...........................
6.3. Low Level Animations .............................................................................
6.3.1. Why Not Just Write Code In Paint? ..............................................
6.4. Transitions ...............................................................................................
6.4.1. Replace .........................................................................................
6.4.2. Slide Transitions ...........................................................................
6.4.3. Fade & Flip Transitions .................................................................
6.4.4. Bubble Transition ..........................................................................
6.4.5. Morph Transitions .........................................................................
6.4.6. SwipeBackSupport ........................................................................
7. The EDT - Event Dispatch Thread ....................................................................
7.1. What Is The EDT ....................................................................................
7.2. Call Serially (And Wait) ...........................................................................

318
319
324
324
324
324
331
333
334
338
341
343
344
344
345
346
347
348
350
351
352
353
354
355
359
360
363
364
365
365
366

vi

Codename One Developer Guide

7.2.1. callSerially On The EDT ............................................................... 367
7.3. Debugging EDT Violations ...................................................................... 368
7.4. Invoke And Block ....................................................................................
8. Monetization ......................................................................................................
8.1. Google Play Ads .....................................................................................
8.2. In App Purchase .....................................................................................
9. Graphics, Drawing, Images & Fonts .................................................................
9.1.
9.2.
9.3.
9.4.
9.5.

Basics - Where & How Do I Draw Manually? .........................................

Glass Pane ..............................................................................................
Shapes & Transforms .............................................................................
Device Support ........................................................................................
A 2D Drawing App ..................................................................................
9.5.1. Implementing addPoint() ...............................................................
9.5.2. Using Bezier Curves .....................................................................
9.5.3. Detecting Platform Support ...........................................................
9.6. Transforms ..............................................................................................
9.6.1. Device Support .............................................................................
9.7. Example: Drawing an Analog Clock ........................................................
9.7.1. The AnalogClock Component .......................................................
9.7.2. Setting up the Parameters ............................................................
9.7.3. Drawing the Tick Marks ................................................................
9.7.4. Drawing the Numbers ...................................................................
9.7.5. Drawing the Hands .......................................................................
9.7.6. The Final Result ............................................................................
9.7.7. Animating the Clock ......................................................................
9.8. Starting and Stopping the Animation ......................................................
9.9. Shape Clipping ........................................................................................
9.10. The Coordinate System ........................................................................
9.10.1. Relative Coordinates ...................................................................
9.10.2. Transforms and Rotations ...........................................................
9.10.3. Event Coordinates .......................................................................
9.11. Images ...................................................................................................
9.11.1. Loaded Image .............................................................................
9.11.2. The RGB Images .......................................................................
9.11.3. EncodedImage ............................................................................
9.11.4. MultiImage ...................................................................................
9.11.5. FontImage & Material Design Icons ............................................
9.11.6. Timeline .......................................................................................

vii

369
374
374
374
377
377
380
383
383
383
385
387
390
390
391
391
392
392
393
395
398
400
401
402
403
404
406
409
416
416
417
418
418
420
420
424

Codename One Developer Guide

9.11.7. Image Masking ............................................................................ 424
9.11.8. URLImage ................................................................................... 426
10. Events ..............................................................................................................
10.1. High Level Events .................................................................................
10.1.1. Chain Of Events ..........................................................................
10.1.2. Action Events ..............................................................................
10.1.3. DataChangeListener ...................................................................

431
431
431
432
435

10.1.4. FocusListener ..............................................................................

10.1.5. ScrollListener ...............................................................................
10.1.6. SelectionListener .........................................................................
10.1.7. StyleListener ................................................................................
10.1.8. Event Dispatcher .........................................................................
10.2. Low Level Events ..................................................................................
10.2.1. Low Level Event Types ...............................................................
10.2.2. Drag Event Sanitation .................................................................
10.3. BrowserNavigationCallback ...................................................................
11. File System, Storage, Network & Parsing .......................................................
11.1. Jar Resources .......................................................................................
11.2. Storage ..................................................................................................
11.2.1. The Preferences API ...................................................................
11.3. File System ...........................................................................................
11.3.1. File Paths & App Home ..............................................................
11.3.2. Storage vs. File System ..............................................................
11.4. SQL .......................................................................................................
11.5. Network Manager & Connection Request .............................................
11.5.1. Threading ....................................................................................
11.5.2. Arguments, Headers & Methods .................................................
11.5.3. GZIP ............................................................................................
11.5.4. File Upload ..................................................................................
11.5.5. Parsing ........................................................................................
11.6. Debugging Network Connections ..........................................................
11.6.1. Simpler Downloads .....................................................................
11.7. Webservice Wizard ...............................................................................
11.8. Cached Data Service ............................................................................
11.9. Externalizable Objects ...........................................................................
11.10. UI Bindings & Utilities .........................................................................
11.11. Logging & Crash Protection ................................................................
11.12. Sockets ................................................................................................

435
436
437
437
437
438
439
440
440
442
442
443
446
447
447
450
451
456
458
459
463
464
465
481
481
483
493
494
498
500
501

viii

Codename One Developer Guide

12. Miscellaneous Features ................................................................................... 505
12.1. Phone Functions ................................................................................... 505
12.1.1. SMS ............................................................................................
12.1.2. Dialing .........................................................................................
12.1.3. E-Mail ..........................................................................................
12.2. Contacts API .........................................................................................
12.3. Localization & Internationalization (L10N & I18N) .................................

505
506
506
507
512

12.3.1. Localization Manager ..................................................................

12.3.2. RTL/Bidi ......................................................................................
12.4. Location - GPS .....................................................................................
12.4.1. Location In The Background - Geofencing ..................................
12.5. Background Music Playback .................................................................
12.6. Capture - Photos, Video, Audio ............................................................
12.6.1. Asynchronous API .......................................................................
12.7. Gallery ...................................................................................................
12.8. Analytics Integration ..............................................................................
12.8.1. Application Level Analytics ..........................................................
12.8.2. Overriding The Analytics Implementation ....................................
12.9. Native Facebook Support ......................................................................
12.9.1. Getting Started - Web Setup .......................................................
12.9.2. IDE Setup ....................................................................................
12.9.3. The Code ....................................................................................
12.9.4. Facebook Publish Permissions ...................................................
12.10. Google Login .......................................................................................
12.10.1. Project Configuration .................................................................
12.10.2. The Code ..................................................................................
12.11. Lead Component .................................................................................
12.11.1. Blocking Lead Behavior ............................................................
12.12. Pull To Refresh ...................................................................................
12.13. Running 3rd Party Apps Using Displays execute ...............................
13. Performance, Size & Debugging .....................................................................
13.1. Reducing Resource File Size ................................................................
13.2. Improving Performance .........................................................................
13.3. Performance Monitor .............................................................................
13.4. Network Speed ......................................................................................
13.5. Debugging Codename One Sources ....................................................
13.6. Device Testing Framework/Unit Testing ...............................................
13.7. EDT Error Handler and sendLog ..........................................................

514
516
518
519
520
521
525
526
527
528
528
528
529
534
534
535
535
543
544
545
547
549
550
552
552
554
555
557
557
558
559

ix

Codename One Developer Guide

14. Advanced Topics/Under The Hood ................................................................. 562
14.1. Sending Arguments To The Build Server ............................................. 562
14.2. The Architecture Of The Old GUI Builder .............................................
14.2.1. Basic Concepts ...........................................................................
14.2.2. IDE Bindings ...............................................................................
14.2.3. Working With The Generated Code ............................................
14.3. Android Permissions .............................................................................

579
580
581
582
584

14.3.1. Permissions Under Marshmallow (Android 6+) ........................... 586

14.4. On Device Debugging ........................................................................... 599
14.4.1. Android Studio Debugging (Easy Way) ....................................... 599
14.4.2. Android Studio Debugging the Hard Way ................................... 600
14.5. Native Interfaces ................................................................................... 600
14.5.1. Objective-C (iOS) ........................................................................ 606
14.5.2. Javascript .................................................................................... 607
14.5.3. Native GUI Components ............................................................. 610
14.5.4. Type Mapping & Rules ............................................................... 611
14.5.5. Android Native Permissions ........................................................ 614
14.5.6. Native AndroidNativeUtil ............................................................. 614
14.5.7. Native Code Callbacks ................................................................ 615
14.6. Libraries - cn1lib .................................................................................... 620
14.6.1. Why Not Use JAR? ..................................................................... 621
14.6.2. How To Use cn1libs? .................................................................. 621
14.6.3. Creating a Simple cn1lib ............................................................. 623
14.6.4. Build Hints in cn1libs .................................................................. 624
14.7. Integrating Android 3rd Party Libraries & JNI ........................................ 629
14.8. Drag & Drop .......................................................................................... 630
14.9. Continuous Integration & Release Engineering .................................... 632
14.10. Android Lollipop ActionBar Customization .......................................... 633
14.11. Intercepting URLs On iOS & Android ................................................. 633
14.11.1. Passing Launch Arguments To The App .................................. 634
14.12. Native Peer Components .................................................................... 635
14.12.1. Why does Codename One Need Native Widgets at all? ........... 635
14.12.2. So whats the problems with native widgets? ............................ 636
14.12.3. So how do we show dialogs on top of Peer Components? ........ 636
14.12.4. Why cant we combine peer component scrolling and Codename
One scrolling? ......................................................................................... 636
14.12.5. Native Components In The First Form ...................................... 637
14.13. Integrating 3rd Party Native SDKs ...................................................... 637

Codename One Developer Guide

14.13.1. Step 1 : Review the FreshDesk SDKs ...................................... 637
14.13.2. Step 2: Designing the Codename One Public API .................... 638
14.13.3. Step 3: The Architecture and Internal APIs ...............................
14.13.4. Step 4: Implement the Public API and Native Interface .............
14.13.5. Step 5: Implementing the Native Interface in Android ...............
14.13.6. Step 6: Bundling the Native SDKs ............................................
14.13.7. Step 7 : Injecting Android Manifest and Proguard Config ..........

638
641
655
658
661

14.14. Part 2: Implementing the iOS Native Code .........................................

14.14.1. Using the MobihelpNativeCallback ............................................
14.14.2. Bundling Native iOS SDK .........................................................
14.14.3. Troubleshooting iOS .................................................................
14.14.4. Adding Required Core Libraries and Frameworks ....................
14.15. Part 3 : Packaging as a .cn1lib ...........................................................
14.16. Building Your Own Layout Manager ...................................................
14.16.1. Porting a Swing/AWT Layout Manager .....................................
15. Signing, Certificates & Provisioning ................................................................
15.1. Common Terms In Signing & Distribution .............................................
15.1.1. What Is A Certificate? .................................................................
15.1.2. What Is Provisioning? .................................................................
15.1.3. Whats a Signing Authority? ........................................................
15.1.4. What is UDID? ............................................................................
15.1.5. Should I Reuse the Same Certificate for All Apps? .....................
15.2. iOS Signing Wizard ...............................................................................
15.2.1. Logging into the Wizard ..............................................................
15.2.2. Selecting Devices ........................................................................
15.2.3. Decisions & Edge Cases ............................................................
15.2.4. App IDs and Provisioning Profiles ...............................................
15.2.5. Installing Files Locally .................................................................
15.2.6. Building Your App .......................................................................
15.3. Advanced iOS Signing ..........................................................................
15.4. Provisioning Profile & Certificates Visual Guide ....................................
15.4.1. iOS Code Signing Failure Checklist ............................................
15.5. Android ..................................................................................................
15.5.1. Generating an Android Certificate Manually ................................
15.6. RIM/BlackBerry ......................................................................................
15.7. J2ME .....................................................................................................
16. Appendix: Working With iOS ...........................................................................
16.1. The iOS Screenshot/Splash Screen Process ........................................

665
666
667
668
668
669
670
673
674
674
674
674
674
675
675
675
676
677
679
682
684
687
688
689
695
700
701
702
702
703
703

xi

Codename One Developer Guide

16.1.1. Size ............................................................................................. 704
16.1.2. Mutable first screen ..................................................................... 705
16.1.3. Unsupported component .............................................................
16.2. Local Notifications on iOS and Android ................................................
16.2.1. Sending Notifications ..................................................................
16.2.2. Receiving Notifications ................................................................
16.2.3. Canceling Notifications ................................................................

705
705
705
707
708

16.3. Push Notifications .................................................................................

16.3.1. What Is Push? ............................................................................
16.3.2. The Push Bureaucracy - Android ................................................
16.3.3. The Push Bureaucracy - iOS ......................................................
16.3.4. Push Client Code ........................................................................
16.3.5. Sending Push Messages ............................................................
16.4. iOS Beta Testing (Testflight) .................................................................
16.5. Accessing Insecure URLs ....................................................................
16.6. Using Cocoapods ..................................................................................
16.6.1. Including Multiple Pods ...............................................................
16.6.2. Other Pod Related Build Hints ....................................................
16.6.3. Converting PodFile To Build Hints ..............................................
17. Appendix: Working With Javascript .................................................................
17.1. Limitations of the Javascript Port ..........................................................
17.1.1. No Multithreaded Code inside Static Initializers ..........................
17.2. Troubleshooting Build Errors .................................................................
17.3. ZIP, WAR, or Preview. Whats the difference? .....................................
17.4. Setting up a Proxy for Network Requests .............................................
17.4.1. Step 1: Setting up a Proxy ..........................................................
17.4.2. Step 2: Configuring your Application to use the Proxy ................
17.5. Customizing the Splash Screen ............................................................
17.6. Debugging .............................................................................................
17.7. Including Third-Party Javascript Libraries .............................................
17.7.1. Libraries vs Resources ...............................................................
17.7.2. The Javascript Manifest File .......................................................
17.8. Browser Environment Variables ............................................................
17.9. Changing the Native Theme .................................................................
17.9.1. Example: Using Android Theme on Android ...............................
18. Deploying UWP Apps ......................................................................................
18.1. Deploying Outside of the Windows App Store (Sideloading) .................
18.1.1. Side-loading to Windows 10 Mobile Devices ..............................

709
709
710
714
716
718
724
724
725
725
726
726
727
727
727
728
729
732
733
733
734
734
735
736
736
741
742
743
744
744
744

xii

Codename One Developer Guide

18.1.2. Side-loading to Windows 10 Desktop Devices ............................ 754
18.1.3. Building for the Windows Store ................................................... 761
18.2. Debugging UWP Apps ..........................................................................
18.2.1. No Line Numbers in Stack Traces ..............................................
19. Appendix: Casual Game Programming ...........................................................
19.1. The Game .............................................................................................
19.1.1. Handling Multiple Device Resolutions .........................................

766
766
769
769
770

19.1.2. Resources ...................................................................................

19.1.3. The Splash Screen .....................................................................
19.1.4. The Game UI ..............................................................................
20. Working With The GUI Builder ........................................................................
20.1. Basic Concepts .....................................................................................
20.1.1. Using Lists In The GUI Builder ...................................................

771
771
772
784
784
785

xiii

List of Tables
2.1. Constraint properties ........................................................................................ 60
4.1. Theme Constants ........................................................................................... 136
4.2. Densities ......................................................................................................... 152
5.1. Java to JavaScript .......................................................................................... 304
5.2. JavaScript to Java .......................................................................................... 304
9.1. Transforms Device Support ............................................................................ 391
10.1. Event type map ............................................................................................ 439
11.1. Compare Storage, FileSystem & Jar Resources .......................................... 451
14.1. Build hints ..................................................................................................... 566
14.2. NativeInterface Supported Types ................................................................. 611
14.3. cn1lib structure ............................................................................................. 628
16.1. iOS Device Screenshot Resolutions ............................................................ 703
17.1. Property hints for the JavaScript port ........................................................... 741

xiv

xv

About This Guide

This developer guide is automatically generated from the wiki pages at https://
github.com/codenameone/CodenameOne/wiki.
You can edit any page within the wiki pages using AsciiDoc and your changes
might make it after review into the official documentation available on the web here:
https://www.codenameone.com/manual/ and available as a PDF file here: https://
www.codenameone.com/files/developer-guide.pdf.
1

We also recommend that you check out the full JavaDoc reference for Codename
One which is very complete.
You can download the full Codename One source code from the Codename One git
2
repository where you can also edit the JavaDocs and submit pull requests to include
3
new features into Codename One .

1
2
3

https://www.codenameone.com/javadoc/
https://github.com/codenameone/CodenameOne/
https://www.codenameone.com/blog/how-to-use-the-codename-one-sources.html

xvi

About This Guide

Authors
This document includes content from multiple authors and community wiki edits. If you
edit pages within the guide feel free to add your name here alphabetized by surname:
Shai Almog

Ismael Baum

Eric Coolman

Chen Fishbein
Steve Hannah
Matt

4
https://github.com/codenameone/
5
https://github.com/Isborg
6
https://twitter.com/ericcoolmandev
7
http://github.com/chen-fishbein/
8
http://github.com/shannah/
9
https://github.com/kheops37

xvii

About This Guide

Rights & Licensing
You may copy/redistribute/print this document without prior permission from Codename
One. However, you may not charge for the document itself although charging for costs
such as printing would be OK.
Notice that while you can print and reproduce sections arbitrarily such changes must
explicitly and clearly state that this is a modified copy and link to the original source at
https://www.codenameone.com/manual/ in a clear way!

xviii

About This Guide

Conventions
This guide uses some notations to provide tips and further guidance.
In case of further information that breaks from the current tutorial flow we use a sidebar
as such:

Sidebar
Dig deeper into some details that dont quite fit into the current flow.
Here are common conventions for highlighting notes:
This is an important note

This is a helpful tip

This is a general informational note, something interesting but not

crucial
This is a warning something we should pay attention to

This convention is used when we refer to a button or a widget to press in the UI. E.g.
press the button labeled Press Here.
Quotes are presented as:
This is a quote
Bold is used for light emphasis on a specific word or two within a sentence.

Sidebar
We use sidebars for things that are an important detour, you can skip them while
reading but you might want to come back and read them later

xix

About This Guide

xx

Chapter1.Introduction
Codename One is a set of tools for mobile application development that derive a great
deal of its architecture from Java.
Codename Ones mission statement is:
Unify the complex and fragmented task of mobile device programming
into a single set of tools, APIs & services. As a result create a
more manageable approach to mobile application development without
sacrificing the power/control given to developers.
This effectively means bringing that old "Write Once Run Anywhere" (WORA)
Java mantra to mobile devices without "dumbing it down" to the lowest common
denominator.

1.1.How Does Codename One Work?

Codename One unifies several technologies and concepts into a single facade:
API - abstracts the differences between the various devices.
Plugin - the only piece of software installed on client machines, it includes the
following features:
IDE integration - preferences, completion, the ability to send a native build
Simulator - native device simulator that runs locally and allows debugging the
application
Designer/GUI Builder - high level tools
Build Servers - The build servers accept native device builds sent by the plugin and
convert the binaries (JARs, not sources) to native applications as explained below.
Cloud Servers - The cloud servers provide features such as push notification, cloud
logging etc.

Introduction

Figure 1.1. The Codename One tool-chain

1.1.1.Why Build Servers?

The build servers allow building native iOS Apps without a Mac and native Windows
apps without a Windows machine. They remove the need to install/update complex
toolchains and simplify the process of building a native app to a right click.
E.g.: Since building native iOS applications requires a Mac OS X machine with a
recent version of xcode Codename One maintains such machines in the cloud. When
developers send an iOS build such a Mac will be used to generate C source code using
1

ParparVM and it will then compile the C source code using xcode & sign the resulting
binary using xcode. You can install the binary to your device or build a distribution binary
for the appstore. Since C code is generated it also means that your app will be "future
proof" in a case of changes from Apple. You can also inject Objective-C native code
into the app while keeping it 100% portable thanks to the "native interfaces" capability
of Codename One.
Subscribers can receive the C source code back using the include sources feature of
Codename One and use those sources for benchmarking, debugging on devices etc.
1

https://github.com/codenameone/CodenameOne/tree/master/vm

Introduction
The same is true for most other platforms. For the Android, J2ME & Blackberry the
standard Java code is executed as is.
2

Java 8 syntax is supported thru retrolambda installed on the Codename One servers.
This is used to convert bytecode seamlessly down to Java 5 syntax levels. Java 5
syntax is translated to the JDK 1.3 cldc subset on J2ME/Blackberry to provide those
language capabilities and APIs across all devices. This is done using a server based
bytecode processor based on retroweaver and a great deal of custom code. Notice that
this architecture is transparent to developers as the build servers abstract most of the
painful differences between devices.

Why ParparVM
3

On iOS, Codename One uses ParparVM which translates Java bytecode to C code
and boasts a non-blocking GC as well as 64 bit/bitcode support. This VM is fully
4
open source in the Codename One git repository . In the past Codename One used
5
XMLVM to generate native code in a very similar way but the XMLVM solution was
6
too generic for the needs of Codename One. ParparVM boasts a unique architecture
of translating code to C (similarly to XMLVM), because of that Codename One is the
only solution of its kind that can guarantee future iOS compatibility since the officially
supported iOS toolchain is always used instead of undocumented behaviors.
XMLVM could guarantee that in theory but it is no longer maintained.

The key advantages of ParparVM over other approaches are:

Truly native - since code is translated to C rather than directly to ARM or LLVM code
the app is "more native". It uses the official tools and approaches from Apple and
can benefit from their advancements e.g. latest bitcode or profiling capabilities.
Smaller class library - ParparVM includes a very small segment of the full JavaAPIs
resulting in final binaries that are smaller than the alternatives by orders of
magnitude. This maps directly to performance and memory overhead.
2

https://github.com/orfjackal/retrolambda
3
https://github.com/codenameone/CodenameOne/tree/master/vm
4
https://github.com/codenameone/CodenameOne/
5
http://www.xmlvm.org/
6
https://github.com/codenameone/CodenameOne/tree/master/vm

Introduction
Simple & extensible - to work with ParparVM you need a basic understanding of C.
This is crucial for the fast moving world of mobile development, as Apple changes
things left and right we need a more agile VM.

Windows Phone/UWP
Codename One has 2 major Windows VM ports and 3 or 4 rendering pipelines within
those ports.
The old Windows Phone port used XMLVM to translate the Java bytecode to C#. Notice
that the XMLVM backend that translates to C# is very different from the one that was
used in the past to translates code for iOS.
Codename One now targets UWP by leveraging a modified version of iKVM to build
native Windows Universal Applications.

JavaScript Port
The JavaScript port of Codename One is based on the amazing work of the TeaVM
7
project . The team behind TeaVM effectively built a JVM that translates Java bytecode
into JavaScript source code while maintaining threading semantics using a very
imaginative approach.
The JavaScript port allows unmodified Codename One applications to run within a
desktop or mobile browser. The port itself is based on the HTML5 Canvas API to provide
a pixel perfect implementation of the Codename One APIs.
The JavaScript port is only available for Enterprise grade subscribers
of Codename One.

Desktop, Android, RIM & J2ME

The other ports of Codename One use the VMs available on the host machines/
8
environments to execute the runtime. Retrolambda is used to provide Java 8 language
features in a portable way, for older devices retroweaver is used to bring Java 5
features.
The Android port uses the native Android tools including the gradle build environment
in the latest versions.
7
8

http://teavm.org:
https://github.com/orfjackal/retrolambda

Introduction
The desktop port creates a standard JavaSE application which is packaged with the
JRE and an installer.
The Desktop port is only available to pro grade subscribers of
Codename One.

Lightweight Components
What makes Codename One stand out is the approach it takes to UI where it
uses a "lightweight architecture" thus allowing the UI to work seamlessly across all
platforms. As a result most of the UI is developed in Java and is thus remarkably
portable and debuggable. The lightweight architecture still includes the ability to embed
"heavyweight" widgets into place among the "lightweights".

Lightweight Architecture Origin

Lightweight components date back to Smalltalk frameworks, this notion was
popularized in the Java world by Swing. Swing was the main source of inspiration
to Codename Ones predecessor LWUIT. Many frameworks took this approach
over the years including JavaFX & most recently Ionic in the JavaScript world.
A Lightweight component is a component that is written entirely in Java, it draws its own
interface and handles its own events/states. This has huge portability advantages since
the same code executes on all platforms, but it carries many additional advantages.
Lightweight components are infinitely customizable by using standard inheritance and
overriding paint/event handling. Since a lightweight component is written entirely in
Java, developers can preview the application accurately in the simulators & GUI builder.
This avoids many common pitfalls of other WORA solutions where platform specific
behavior foiled any saved effort. Hence all the effort saved in coding was lost in
debugging esoteric device only oddities.
Codename One achieves fast performance by drawing using the native gaming APIs
of most platforms e.g. OpenGL ES on iOS.

1.1.2.Versions In Codename One

One of the confusing things about Codename One is the versions. Since Codename
One is a SaaS product versioning isnt as simple as a 2.x or 3.x moniker. However,
5

Introduction
to conform to this convention Codename One does make versioned releases which
contribute to the general confusion.
When a version of Codename One is released the version number refers to the libraries
at the time of the release. These libraries are then frozen and are made available to
9
developers who use the Versioned Builds feature. The plugin, which includes the
designer as well as all development that is unrelated to versioned builds continues with
its regular updates immediately after release. The same is true for the build servers
that move directly to their standard update cycle.

1.2.History

Figure 1.2. LWUIT App Screenshot circa 2007

Codename One was started by Chen Fishbein & Shai Almog who authored the Open
Source LWUIT project at Sun Microsystems starting at 2007. The LWUIT project
aimed at solving the fragmentation within J2ME/Blackberry devices by creating a higher
standard of user interface than the common baseline at the time. LWUIT received
critical acclaim and traction within multiple industries but was limited by the declining
feature phone market. It was forked by several companies including Nokia, it was used
as the base standard for DTV in Brazil. Another fork has brought a LWUIT fork into
high end cars from Toyota and other companies. This fork later adapted Codename
One as well.
In 2012 Shai & Chen formed Codename One as they left Oracle. The project has
taken many of the basic concepts developed within the LWUIT project and adapted
them to the smartphone world which is still experiencing similar issues to the device
fragmentation of the old J2ME phones.
9

https://www.codenameone.com/how-do-i---get-repeatable-builds-build-against-a-consistent-version-of-

codename-one-use-the-versioning-feature.html

Introduction

1.3.Installation
1.3.1.Installing Codename One In NetBeans
For the purpose of this document we will focus mostly on the NetBeans IDE for
development, however most operations are almost identical in the Eclipse IDE as well.
Eclipse installation instructions are in the next section.
These instructions assume you have downloaded a recent version of NetBeans (at this
time 8.x), installed and launched it.
Select the ToolsPlugins menu option

Figure 1.3. ToolsPlugin menu option

Select the Available Plugins Tab
Check The CodenameOne Plugin

Introduction

Figure 1.4. Netbeans Plugin Install Wizard

click the install button below. Follow the Wizard instructions to install the plugin

Introduction

Figure 1.5. Netbeans Plugin Install Wizard step 2

1.3.2.Installing Codename One In Eclipse

Startup Eclipse and click Help `Install New Software`. You should get this dialog

Introduction

Figure 1.6. Eclipse Install New Software

Click the Add button on the right side & fill out the entries

Figure 1.7. Eclipse Add Repository Dialog

10

Introduction
Enter Codename One for the name and https://www.codenameone.com/
files/eclipse/site.xml for the location.
Select the entries & follow the wizard to install

Figure 1.8. Eclipse Install Wizard select entries

1.3.3.Installing Codename One In IntelliJ IDEA

Download & install IntelliJ/IDEA, notice that Android Studio will not work.
Install the plugin using The Plugin Center
Use the search functionality in the plugin center to find and install the Codename One
plugin.

11

Introduction

1.4.Hello World Application

This hello world application uses NetBeans but it should work just as well for Eclipse/
IntelliJ.
Start by selecting the new project button (or menu item) in the IDE and selecting the
Codename One project option.

Figure 1.9. New Project

Figure 1.10. New Project Dialog

12

Introduction

Figure 1.11. New Project Dialog Step 2 - Select the project name/
location
Use a proper package name for the project!

13

Introduction

Figure 1.12. Setting a proper package name

Package Names & Unique Ids

A good package name in a project is crucial and very hard/impossible to change
after the fact. App stores recognize your app based on its package name so if
you would want/need to change that in the future this might become impossible.
The convention used both by Java, itunes, google play etc. is to use a reverse
domain notation. E.g. if your company is called "ACME" and has the domain
acme.com. Your package names should start with com.acme
A common mistake is to put your project directly in the root package of your
company which will make it inconvenient to position future projects from your
company so use something similar to com.acme.myapp as your package
name.
By default a nice looking hello world project is created. We will maintain this default for
the purpose of this walk-thru.
14

Introduction

Figure 1.13. Default project structure

There are two important files that are generated:
SuperDuperApp.java - your main java source file, this is where your app starts/
stops and handles system notifications (e.g push).
theme.res - the theme file contains the application styling, localization, images
etc.
When we double click the theme.res file it opens in the Codename One designer
tool. We can then edit the styles of any element within the theme.
We will cover this further in Basics Of Codename One. We will also dig deeper into
theming in Codename One Theme Basics.

Figure 1.14. The default theme created in the hello world wizard
15

Introduction
To run the application just press the IDEs play button and you should see something
similar to Figure 1.15, The default hello world Codename One app

Figure 1.15. The default hello world Codename One app

1.4.1.The Source Code Of The Hello World App

The hello world wizard generates a bit of code well deconstruct it into smaller pieces
to understand the inner workings of Codename One.
package com.acme.superduperapp;
import com.codename1.io.Log;

import com.codename1.ui.Button;

import com.codename1.ui.Display;

import com.codename1.ui.FontImage;
import com.codename1.ui.Form;

import com.codename1.ui.Label;

16

Introduction
import com.codename1.ui.animations.CommonTransitions;
import com.codename1.ui.layouts.BorderLayout;
import com.codename1.ui.layouts.BoxLayout;

import com.codename1.ui.layouts.FlowLayout;

import com.codename1.ui.layouts.LayeredLayout;
import com.codename1.ui.plaf.UIManager;
import com.codename1.ui.util.Resources;
import com.codename1.ui.util.UITimer;
import java.io.IOException;

public class SuperDuperApp {

private Form current;

private Resources theme;

public void init(Object context) {

theme = UIManager.initFirstTheme("/theme");
// Pro only feature, uncomment if you have a pro subscription

// Log.bindCrashProtection(true);

public void start() {

if(current != null){
current.show();

return;

Form hi = new Form("Welcome", new

BorderLayout(BorderLayout.CENTER_BEHAVIOR_CENTER_ABSOLUTE));

final Label apple = new Label(theme.getImage("apple-icon.png"));

final Label android = new Label(theme.getImage("android-

icon.png"));

final Label windows = new Label(theme.getImage("windows-

icon.png"));

Button getStarted = new Button("Let's Get Started!");

FontImage.setMaterialIcon(getStarted, FontImage.MATERIAL_LINK);
getStarted.setUIID("GetStarted");
hi.addComponent(BorderLayout.CENTER,
LayeredLayout.encloseIn(
BoxLayout.encloseY(
new Label(theme.getImage("duke-no-

logos.png")),

);

getStarted

),
FlowLayout.encloseRightMiddle(apple)

17

Introduction

getStarted.addActionListener((e) -> {
Display.getInstance().execute("https://www.codenameone.com/
developers.html");
});

new UITimer(() -> {

if(apple.getParent() != null) {

apple.getParent().replace(apple, android,
CommonTransitions.createFade(500));
} else {

if(android.getParent() != null) {

android.getParent().replace(android, windows,
CommonTransitions.createFade(500));
} else {

windows.getParent().replace(windows, apple,
CommonTransitions.createFade(500));
}

}
}).schedule(2200, true, hi);
hi.show();

public void stop() {

}

current = Display.getInstance().getCurrent();

public void destroy() {

}

The class package and import statements should be self explanatory so well focus on
the class itself:
public class SuperDuperApp {
private Form current;

private Resources theme;

public void init(Object context) {
}

public void start() {

}

public void stop() {

18

Introduction
}
public void destroy() {
}

The main class doesnt implement any interface or extend a base class, however the
Codename One runtime expects it to have these 4 methods and maintain the method
signatures.
A common mistake developers make is writing code that throws a
checked exception and then letting the IDE "auto-correct" the code
by adding a throws clause to the parent method. This will fail during
a device build.
We also keep two variables by default in a hello world application:
theme - allows us to set the look of the application. A theme object maps to the
theme.res file where a lot of data can be stored e.g. images, localization etc.
10

current - the current application Form . A Form is the top level class
responsible for placing a UI in Codename One. Think of it as you would think
about a Frame in AWT, JFrame in Swing, Activity + View in Android,
UIController + View in iOS & the html tag in HTML.
This variable is used for the Suspend/Resume Behavior of the application.
The 4 builtin methods of the Codename One main class include:
init(Object) - invoked when the application is started but not when its restored
from the background. E.g. if the app isnt running, init will be invoked. However,
if the app was minimized and is then restored init will not be invoked.

This is a good place to put generic initializations of variables and the likes. We
specifically use it to initialize the theme which is something we normally need to do
only once per application execution.
The object passed to init is the native OS context object, it can be null but can be
ignored for 99% of the use cases.

start() - the start method is invoked with every launch of the app. This includes
restoring a minimized application. This is very useful for initializing UIs which usually
need to be refreshed both when the user launches the app and when he returns to
it after leaving it in the background for any duration.
10

http://codenameone.com/javadoc/com/codename1/ui/Form.html

19

Introduction
stop() - stop is invoked when the user minimizes the app. If you have ongoing
operations (e.g. download/media) you should stop them here or the operating
system might kill your application due to CPU usage in the background.
destroy() - this callback isnt guaranteed since an OS might kill the app and
neglect to invoke this method. However, most OSs will invoke this method before
completely closing the app. Since stop() will be invoked first its far better to write
code there.
By default Codename One applications save/restore the current form with code like this:
public void start() {

if(current != null){
current.show();

return;

// rest of start method....

public void stop() {

current = Display.getInstance().getCurrent();

Now all that remains is the content of the start() method, well break the body into
a few pieces for clarity:
Form hi = new Form("Welcome", new

BorderLayout(BorderLayout.CENTER_BEHAVIOR_CENTER_ABSOLUTE));
11

In this block we create a new Form named hi . We give it the title "Welcome"
which will be displayed at the top. We also define the layout manager of the form to
12
BorderLayout which allows us to place a component in one of 5 positions. In this case
the BorderLayout allows us to place the component in the center of the screen.
Normally a BorderLayout stretches the center component to take up the whole
screen but we want Duke to be completely centered so we ask the layout to use the
CENTER_BEHAVIOR_CENTER_ABSOLUTE behavior.
You can learn more about positioning components with layouts in the Layout Managers
section.
11
12

https://www.codenameone.com/javadoc/com/codename1/ui/Form.html
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/BorderLayout.html

20

Introduction

final Label apple = new Label(theme.getImage("apple-icon.png"));

final Label android = new Label(theme.getImage("android-icon.png"));

final Label windows = new Label(theme.getImage("windows-icon.png"));
13

We create the images for the logos that fade in Dukes hand. We use the Label
class to display the images. Notice that we get the images themselves from the theme
resource file.

Multi Images
We could load a PNG directly from file but using the resource file carries an
advantage as we can use multi images. Multi-images are a set of images adapted
14
to device density .
A high resolution image is used during development and the Codename One
designer adapts it to the various DPIs. This simplifies the process of dealing with
multiple device densities.
You can learn more about multi-images in the Section 4.7, Understanding
Images & Multi-Images section.

Button getStarted = new Button("Let's Get Started!");

FontImage.setMaterialIcon(getStarted, FontImage.MATERIAL_LINK);
15

The getStarted Button is pretty self explanatory however the next line installing
the font image isnt as clear.
16
FontImage allows us to take a font (TTF) and use it as an icon or an image. This is
quite powerful as fonts are rendered smoothly in every device density & can easily be
adapted to theme conventions/colors.
17

Codename One has the material design icon font built into it, this provides a good
set of basic icons that all applications can reuse across all platforms. You can also pick
13
https://www.codenameone.com/javadoc/com/codename1/ui/Label.html
14
density indicates the amount of pixels for a given square inch of screen space e.g. an older iOS device
would have 160ppi (pixels per inch) whereas iPhone 6+ has 540 ppi!
15
https://www.codenameone.com/javadoc/com/codename1/ui/Button.html
16
https://www.codenameone.com/javadoc/com/codename1/ui/FontImage.html
17
https://www.google.com/design/icons/

21

Introduction
a custom icon font and make use of that using one of the many resources available
on the web.
The FontImage class allows us to create an Image
19

18

object but in this case we chose

to use setMaterialIcon . The benefit of using that approach is simple, this method
automatically uses the buttons styling (color, font size etc.) for the icon image.
getStarted.setUIID("GetStarted");
20

The setUIID
method allows us to define the theme styling used for a given
component. By default a button would use the "Button" UIID so by changing this
the button will have a different look.
To understand what that would look like just double click the theme.res file and

select the theme. Then double click the "GetStarted" entry in the list, you should see
something like this:

18
https://www.codenameone.com/javadoc/com/codename1/ui/Image.html
19
https://www.codenameone.com/javadoc/com/codename1/ui/FontImage.html#setMaterialIconcom.codename1.ui.Label-char20
https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#setUIID-java.lang.String-

22

Introduction

Figure 1.16. The GetStarted UIID in the theme file

We will discuss theming further in Basics Of Codename One.
hi.addComponent(BorderLayout.CENTER,
LayeredLayout.encloseIn(
BoxLayout.encloseY(

new Label(theme.getImage("duke-no-logos.png")),

);

getStarted
),
FlowLayout.encloseRightMiddle(apple)

The code above is a bit terse, it uses the shortened syntax for Codename One, if you
are used to other frameworks a slightly more verbose version of the same code might
be clearer:
Container tmpBoxLayout = new Container(new BoxLayout(BoxLayout.Y_AXIS));
tmpBoxLayout.add(new Label(theme.getImage("duke-no-logos.png")));

23

Introduction
tmpBoxLayout.add(getStarted);

Container tmpFlowLayout = new Container(new FlowLayout(Component.LEFT,

Component.CENTER));
tmpFlowLayout.add(apple);

Container tmpLayeredContainer = new Container(new LayeredLayout());

tmpLayeredContainer.add(tmpBoxLayout);
tmpBoxLayout.add(tmpFlowLayout);
hi.addComponent(BorderLayout.CENTER,tmpLayeredContainer);

What we are doing here is creating a Component

be used to render them onto the screen.

21

Container

22

hierarchy that can

The Component -> Container Hierarchy section discusses this subject further.
23

The root Container is the hi Form

onto which we add a Container
24
with a LayeredLayout . This means that the elements placed directly into that
LayeredLayout will be positioned one on top of the other, we need that so the logos
for the supported platforms will appear in Dukes hand.
25

Then we place two containers, the first is a BoxLayout container on the Y axis. This
means the elements within this layout will order themselves vertically in a column. We
place the image for Duke within this layout followed by the button.
26

Next within the LayeredLayout we have a FlowLayout that is positioned to the

right horizontally and to the middle of the available space vertically. This allows us to
place the logos in Dukes hand which is roughly in that position. Initially we place the
Apple logo within that layout and below well cover the code that animates that logo.
You can gain insight into the Codename One component hierarchy
by running the simulator and selecting the SimulateComponent
Inspector menu option. This will present the component hierarchy as
a navigatable tree.

21
https://www.codenameone.com/javadoc/com/codename1/ui/Component.html
22
https://www.codenameone.com/javadoc/com/codename1/ui/Container.html
23
https://www.codenameone.com/javadoc/com/codename1/ui/Form.html
24
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/LayeredLayout.html
25
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/BoxLayout.html
26
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/FlowLayout.html

24

Introduction

Figure 1.17. Component hierarchy for the getting started hello world
app
getStarted.addActionListener((e) -> {
Display.getInstance().execute("https://www.codenameone.com/
developers.html");
});

We can use event callbacks to perform actions within a Codename One application. In
this case we are launching the browser to the Codename One website.
This code snippet uses Java 8 lambda syntax for simplicity. It is
functionally equivalent to this listing.

getStarted.addActionListener(new ActionListenr() {
public void actionPerformed(ActionEvent e) {

Display.getInstance().execute("https://www.codenameone.com/
developers.html");
}
});

You can learn more about event handling in Codename One in the Events Section.
new UITimer(() -> {
//...

}).schedule(2200, true, hi);

25

Introduction
hi.show();

Well come back to the body of the UITimer

concept

27

soon. But first lets discuss the general

The UITimer class allows us to receive a callback within a fixed period of time. Here
we schedule the timer to repeat (the true argument) every 2200 milliseconds. We
need to bind this timer to the parent form, when we navigate to a different form it will
no longer be active.
Java contains a Timer class within the java.util package.
However its invoke within a separate thread which can cause issues
when dealing with UI. The UITimer class can be used to handle
UI in a seamless way.
As the final line of code in this demo we just show the form which should be self
explanatory.
if(apple.getParent() != null) {

apple.getParent().replace(apple, android,
CommonTransitions.createFade(500));

} else {

if(android.getParent() != null) {

android.getParent().replace(android, windows,
CommonTransitions.createFade(500));
} else {

windows.getParent().replace(windows, apple,
CommonTransitions.createFade(500));
}

The UITimer callback just replaces one component with another and uses the fade
28
29
transition for the replace operation.
It checks the current state by checking if the parent component is null . E.g. when
we replace the apple label with the android label the parent container for apple
will become null .
27
28

https://www.codenameone.com/javadoc/com/codename1/ui/util/UITimer.html
https://www.codenameone.com/javadoc/com/codename1/ui/animations/

CommonTransitions.html#createFade-int29
https://www.codenameone.com/javadoc/com/codename1/ui/Container.html#replacecom.codename1.ui.Component-com.codename1.ui.Component-com.codename1.ui.animations.Transition-

26

Introduction

1.4.2.Building & Deploying On Devices

Figure 1.18. Codename One project preferences

You can use the project settings to configure almost anything. Specifically, the
application title, application version, application icon etc. are all found in the project
properties in the right click menu of your IDE.

Certificates
The most crucial thing for a final app is the developer certificate. The certificate indicates
who the author of the app is and without it you wont be able to ship your app or update
your app.
Backup your Android certificate and save its password! We cant
stress this enough!
If you lose your Android certificate you will not be able to update your
app.
To create an Android or iOS certificate just use the generate button within the respective
section in the preferences.
27

Introduction
To generate an iOS certificate you will need an Apple developer
account which needs to be purchased from Apple and has a waiting
period for approval (less than a week).
Certificates and provisioning are a big & complex subject that we cover in depth in the
signing section.
You can reuse both Android and iOS certificates for all your
applications. However, for iOS you will need to create provisioning
profiles for every application.

Sending A Build
In order to get a native application for the devices you need to send a build to the build
server. For that purpose you will need to signup at https://www.codenameone.com/ and
click on the email validation link.
Once you signed up you can right click the project and select one of the build target
options and a build will be sent to the servers.
Desktop & JavaScript builds are for high grade paying subscriptions.
Free subscribers have a build quota limit imposed monthly and a jar
size limit. This are in place to prevent excessive build server resource
consumption.

28

Introduction

Figure 1.19. Right click menu options for sending device builds
Once the build is sent successfully you can get the result at https://
www.codenameone.com/build-server.html

29

Introduction

Figure 1.20. Build results on codenameone.com allow us to scan

the QR code with our device to install instantly
Older builds are cleared within 3 days from the build servers.

You can install the application either by scanning the QR code or emailing the install
link to your account (using the e-mail Link button).
You can download the binaries in order to upload them to the appstores.

1.5.Application Lifecycle
Now that we have a basic understanding of Codename One its probably a good point
to explain a core idea about the code above. Every Codename One application has a
main class which serves as its "entry point". This class has the following 4 methods:
public void init(Object context) {}
public void start() {}
public void stop() {}

public void destroy() {}

These provide a set of simplified hooks into the application state in the operating
system.
30

Introduction
Android developers are used to Activity which provides a similar
set of methods and far more functionality. However, since Activities
are unique to Android their functionality cannot be reproduced in a
portable way.
Applications are always launched with a call to init(Object) , for historical reasons
a native context object is passed but its often null and when it isnt we dont really need
it anyway.
All Codename One callback methods are invoked on the event
dispatch thread (EDT) which is the main thread of Codename One.
Doing things like sleep loops or long running tasks within them is
strictly prohibited.
init(Object) is a great place to initialize everything that needs to always be there.
E.g. your application theme, crash protection etc.
start() is invoked immediately after init(Object) and every time an app is
restored from background (more on that below).
stop() is invoked when the app is sent to background or minimized.
destroy() might be invoked when an app is killed by the OS. There is no guarantee
that destroy will be invoked!

1.5.1.Suspend/Resume
Suspend happens when an app is minimized e.g. when a user presses the home button,
when an incoming call takes over the phone etc.
These operations suspend the app and send it into suspended state. If the user chooses
to return to a running app the app isnt started from scratch, its resumed.
The behavior of the app during its suspended state is very OS specific but all OSs place
heavy restrictions on background operations. When an app is minimized its expected
that it will quit all non-essential work (e.g. networking operations).
This means you should stop all of the "expensive" operations such as networking,
GPS etc. when the stop() method is invoked and potentially restore them when
start() is invoked.
You can simulate suspend/resume in the simulator menu, this wont simulate the OS
killing of your app but will allow you to debug the logic in the start() / stop()
methods.
31

Chapter2.Basics: Themes, Styles,

Components & Layouts
This chapter covers the basic ideas underlying Codename One focusing mostly on the
issues related to UI :icons: font

2.1.What Is A Theme, What Is A Style & What Is a

Component?
1

Every visual element within Codename One is a Component , the button on the screen
2
is a Component and so is the Form in which its placed. This is all represented within
the Component , which is probably the most central class in Codename One.
Every component has 4 standard style objects associated with it: Selected ,
Unselected , Disabled & Pressed .
If you wish to set a value to all component states you can use
getAllStyles() which implicitly sets all the different styles.
Notice that you must use it for write operations ( set ) and never use
it for read operations ( get ).
Only one style is applicable at any given time and it can be queried via the
getStyle() method. A style contains the colors, fonts, border and spacing
information relating to how the component is presented to the user.
You should not use getStyle() in normal execution but instead
use
getUnselectedStyle() ,
getSelectedStyle() ,
getPressedStyle()
&
getDisabledStyle() .
The
reasoning is simple, getStyle() might return any one of those 4
depending on component state and you might not get the result you
want. You should only use`getStyle()` when painting the component
(e.g. in the paint callback method) to query information and not
to set information.

1
2

https://www.codenameone.com/javadoc/com/codename1/ui/Component.html
https://www.codenameone.com/javadoc/com/codename1/ui/Form.html

32

Basics: Themes, Styles, Components & Layouts

A theme allows the designer to define the styles externally via a set of UIIDs (User
Interface IDs), the themes are created via the Codename One Designer tool and allow
developers to separate the look of the component from the application logic.

2.2.Native Theme
By default Codename One applications are created with a theme that derives from
the builtin OS native theme. You can add additional themes into the resource file by
pressing the Add A New Theme button. You can also create multiple themes and ship
them with your app or download them dynamically.
You can create a theme from scratch or customize one of the Codename one themes
to any look you desire.
To preview the look of your theme in the various platforms use the
Native Theme menu option in the designer.

Figure 2.1. The native theme menu option

You can easily create deep customizations that span across all themes by adding a
UIID or changing an existing UIID. E.g. going back to our original hello world application
the "GetStarted" UIID is defined within the designer as:
A green background
White forground
A thin medium sized font
Center aligned text
A small amount of spacing between the text and the edges
33

Basics: Themes, Styles, Components & Layouts

To achieve the colors we define them in the color tab.
We define the transparency to 255 which means the background
will be a solid green color. This is important since the native OSs
might vary with the default value for background transparency so this
should be defined explicitly.

Figure 2.2. The Color tab for the get started button theme settings
The alignment of the text is pretty simple, notice that the alignment style attribute applies
to text and doesnt apply to other elements. To align other elements we use layout
manager logic.

34

Basics: Themes, Styles, Components & Layouts

Figure 2.3. The alignment tab for the get started button theme
settings
Padding can be expressed in pixels, millimeters (approximate) or percentages of the
screen size.
We recommend using millimeters for all measurements to keep the
code portable for various device DPIs.

35

Basics: Themes, Styles, Components & Layouts

Figure 2.4. The padding tab for the get started button theme settings
The font uses native OS light font but has a fallback for older OSs that dont support
truetype fonts. The "True Type" font will be applicable for most modern OSs. In the
case of the "native:" fonts Android devices will use Roboto whereas iOS devices will
use Helvetica Neue. You can supply your own TTF and work with that.
Since Codename One cannot legally ship Helvetica Neue fonts the
simulator will fallback to Roboto on PCs.
At the time of this writing the desktop/simulator version of the Roboto
font doesnt support many common character sets (languages). This
will have no effect on an Android device where thenative font works
properly.

36

Basics: Themes, Styles, Components & Layouts

Figure 2.5. The font tab for the get started button theme settings

2.3.Component/Container Hierarchy

Figure 2.6. Codename One Simplified Component Hierarchy

The component class is the basis of all UI widgets in Codename One, to arrange
3
multiple components together we use the Container class which itself IS A
3

https://www.codenameone.com/javadoc/com/codename1/ui/Container.html

37

Basics: Themes, Styles, Components & Layouts

4

Component subclass. The Container is a Component that contains Components

effectively allowing us to nest Containers infinitely to build any type of visual hierarchy
we want by nesting Containers.

Figure 2.7. Component UML

2.4.Layout Managers
5

Layout managers are installed on the Container class and effectively position the
Components within the given container. The Layout class is abstract and allows
users to create their own layout managers, however Codename One ships with multiple
layout managers allowing for the creation of many layout types.
The layout managers are designed to allow developers to build user interfaces that
seamlessly adapt to all resolutions and thus dont state the component size/position
but rather the intended layout behavior.
To install a layout manager one does something like this:
Container c = new Container(new BoxLayout(BoxLayout.X_AXIS));
c.addComponent(new Button("1"));
c.addComponent(new Button("2"));
c.addComponent(new Button("3"));

This would produce 3 buttons, one next to the other horizontally.

This can also be expressed using a shorter syntax since the add method returns a
container:
4
5

https://www.codenameone.com/javadoc/com/codename1/ui/Component.html
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/Layout.html

38

Basics: Themes, Styles, Components & Layouts

Container c = new Container(new BoxLayout(BoxLayout.X_AXIS)).

add(new Button("1")).
add(new Button("2")).
add(new Button("3"));

The add method can also accept an Image or a String. This will
effectively wrap such data in a label so add("abc") would be
equivalent to add(new Label("abc")) .

There is an even shorter version since most layout managers have helper methods to
6
7
facilitate smaller code sizes e.g. BoxLayout has encloseX(Component) that can
be used as such:
Container c = BoxLayout.encloseX(new Button("1"),

new Button("2"), new Button("3"));

2.4.1.Constraint Based Layout Managers

There are two major types of layout managers:
Constraint based & regular. The regular layout managers like the box layout are
just installed on the container and do their job. The constraint based layout
8
managers associate a value with a Component sometimes explicitly and sometimes
9
10
implicitly. Codename One ships with 5 such layouts BorderLayout , TableLayout ,
11
12
13
GridBagLayout , GroupLayout & MigLayout .
A constraint layout CAN accept a value when adding the component to indicate its
14
position. Notice that some layout manager require such a value (e.g. BorderLayout
will throw an exception if a constraint is missing) whereas other constraint based layout
managers will fallback to a sensible default (e.g. TableLayout

15

).

6
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/BoxLayout.html
7
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/BoxLayout.html#encloseXcom.codename1.ui.Component8
https://www.codenameone.com/javadoc/com/codename1/ui/Component.html
9
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/BorderLayout.html
10
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/TableLayout.html
11
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/GridBagLayout.html
12
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/GroupLayout.html
13
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/mig/MigLayout.html
14
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/BorderLayout.html
15
https://www.codenameone.com/javadoc/com/codename1/ui/table/TableLayout.html

39

Basics: Themes, Styles, Components & Layouts

You can use a constraint based layout like BorderLayout

16

using syntax like this:

Container c = new Container(new BorderLayout());

c.addComponent(BorderLayout.CENTER, new Button("1"));

c.addComponent(BorderLayout.NORTH, new Button("2"));
c.addComponent(BorderLayout.SOUTH, new Button("3"));

This will stretch button 1 across the center of the container and buttons 2-3 will be
stretched horizontally at the top and bottom of the container.
The order to adding doesnt mean much for most constraint based
layouts involved.
Like the above sample code this too can be written using terse syntax e.g.:
Container c = new Container(new BorderLayout()).

add(BorderLayout.CENTER, new Button("1")).

add(BorderLayout.NORTH, new Button("2")).
add(BorderLayout.SOUTH, new Button("3"));

This can also be written with a helper method from the layout e.g.
Container c = BorderLayout.center(new Button("1")).
add(BorderLayout.NORTH, new Button("2")).
add(BorderLayout.SOUTH, new Button("3"));

2.4.2.Understanding Preferred Size

17

The Component class contains many useful methods, one of the most important ones
is calcPreferredSize() which is invoked to recalculate the size a component
wants when something changes
By default Codename One invokes the getPreferredSize()
method and not calcPreferredSize() directly.
getPreferredSize() invokes calcPreferredSize() &
caches the value.
16
17

https://www.codenameone.com/javadoc/com/codename1/ui/layouts/BorderLayout.html
https://www.codenameone.com/javadoc/com/codename1/ui/Component.html

40

Basics: Themes, Styles, Components & Layouts

The preferred size is decided by the component based on many constraints such as
the font size, border sizes, padding etc.
When a layout manager positions & sizes the component, it MIGHT take the preferred
size into account. Notice that it MIGHT ignore it entirely!
E.g. FlowLayout
19

18

always gives components their exact preferred size, yet

BorderLayout resizes the center component by default (and the other components
on one of their axis).
You can define a group of components to have the same preferred width or height by
using the setSameWidth & setSameHeight methods:
Component.setSameWidth(cmp1, cmp2, cmp3, cmp4);
Component.setSameHeight(cmp5, cmp6, cmp7);

Setting The Preferred Size

Codename One has a setPreferredSize method that allows developers to
explicitly request the size of the component. However, this caused quite a lot
of problems since the preferred size should change with device orientation or
similar operations. The API also triggered frequent inadvertant hardcoding of UI
values. As a result the method was deprecated.
We recommend developers use setSameWidth , setSameHeight when
sizing alignment is needed. setHidden when hiding is needed. As a last resort
we recommend overriding calcPreferredSize .

18
19

https://www.codenameone.com/javadoc/com/codename1/ui/layouts/FlowLayout.html
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/BorderLayout.html

41

Basics: Themes, Styles, Components & Layouts

2.4.3.Flow Layout

Figure 2.8. Flow Layout

20

Flow layout can be used to just let the components flow horizontally and break a line
when reaching the edge of the container. It is the default layout manager for containers,
but because it is so flexible it is often problematic as it can cause the preferred size
21
of the Container to provide false/misleading information, triggering endless layout
reflows.
20
21

https://www.codenameone.com/javadoc/com/codename1/ui/layouts/FlowLayout.html
https://www.codenameone.com/javadoc/com/codename1/ui/Container.html

42

Basics: Themes, Styles, Components & Layouts

Form hi = new Form("Flow Layout", new FlowLayout());

hi.add(new Label("First")).

add(new Label("Second")).
add(new Label("Third")).

add(new Label("Fourth")).
add(new Label("Fifth"));

hi.show();

Flow layout also supports terse syntax shorthand such as:

Container flowLayout = FlowLayout.encloseIn(
new Label("First"),

new Label("Second"),
new Label("Third"),

new Label("Fourth"),

new Label("Fifth")));

Flow layout can be aligned to the left (the default), to the center, or to the right. It can
also be vertically aligned to the top (the default), middle (center), or bottom.

43

Basics: Themes, Styles, Components & Layouts

Figure 2.9. Flow layout aligned to the center

44

Basics: Themes, Styles, Components & Layouts

Figure 2.10. Flow layout aligned to the right

45

Basics: Themes, Styles, Components & Layouts

Figure 2.11. Flow layout aligned to the center horizontally & the
middle vertically
Components within the flow layout get their natural preferred size by default and are
not stretched in any axis.
The natural sizing behavior is often used to prevent other
layout managers from stretching components. E.g. if we have a
border layout element in the south and we want it to keep its
natural size instead of adding the element to the south directly
we can wrap it using parent.add(BorderLayout.SOUTH,
FlowLayout.encloseCenter(dontGrowThisComponent)) .
46

Basics: Themes, Styles, Components & Layouts

2.4.4.Box Layout
box-layout-x-no-grow
22

BoxLayout places elements in a row ( X_AXIS ) or column ( Y_AXIS ) according

to box orientation. Box is a very simple and predictable layout that serves as the
"workhorse" of component lists in Codename One.
You can create a box layout Y using something like this:
Form hi = new Form("Box Y Layout", new BoxLayout(BoxLayout.Y_AXIS));
hi.add(new Label("First")).

add(new Label("Second")).
add(new Label("Third")).

add(new Label("Fourth")).
add(new Label("Fifth"));

Which results in this

22

https://www.codenameone.com/javadoc/com/codename1/ui/layouts/BoxLayout.html

47

Basics: Themes, Styles, Components & Layouts

Figure 2.12. BoxLayout Y

Box layout also supports a shorter terse notation which we use here to demonstrate
the X axis box.
Container box = BoxLayout.encloseX(new Label("First"),
new Label("Second"),
new Label("Third"),

new Label("Fourth"),

new Label("Fifth")));

48

Basics: Themes, Styles, Components & Layouts

Figure 2.13. BoxLayout X

The box layout keeps the preferred size of its destination orientation and scales
elements on the other axis. Specifically X_AXIS will keep the preferred width of the
component while growing all the components vertically to match in size. Its Y_AXIS
counterpart keeps the preferred height while growing the components horizontally.
This behavior is very useful since it allows elements to align as they would all have
the same size.
In some cases the growing behavior in the X axis is undesired, for these cases we can
use the X_AXIS_NO_GROW variant.
49

Basics: Themes, Styles, Components & Layouts

Figure 2.14. BoxLayout X_AXIS_NO_GROW

Comparing FlowLayout & BoxLayout - There are quite a
few differences between FlowLayout and BoxLayout . When it
doesnt matter to you we recommend BoxLayout as it acts more
consistently in all situations & is far simpler. Another advantage of
BoxLayout is the fact that it grows and thus aligns nicely.

50

Basics: Themes, Styles, Components & Layouts

2.4.5.Border Layout

Figure 2.15. Border Layout

23

Border layout is quite unique, its a constraint-based layout that can place up to 5
components in one of the 5 positions: NORTH , SOUTH , EAST , WEST or CENTER .
Form hi = new Form("Border Layout", new BorderLayout());
hi.add(BorderLayout.CENTER, new Label("Center")).
add(BorderLayout.SOUTH, new Label("South")).
add(BorderLayout.NORTH, new Label("North")).
add(BorderLayout.EAST, new Label("East")).
add(BorderLayout.WEST, new Label("West"));

hi.show();

The layout always stretches the NORTH / SOUTH components on the X-axis to
completely fill the container and the EAST / WEST components on the Y-axis. The
center component is stretched to fill the remaining area by default. However, the
setCenterBehavior allows us to manipulate the behavior of the center component
so it is placed in the center without stretching.
23

https://www.codenameone.com/javadoc/com/codename1/ui/layouts/BorderLayout.html

51

Basics: Themes, Styles, Components & Layouts

E.g.:
Form hi = new Form("Border Layout", new BorderLayout());

((BorderLayout)hi.getLayout()).setCenterBehavior(BorderLayout.CENTER_BEHAVIOR_CENTER);
hi.add(BorderLayout.CENTER, new Label("Center")).
add(BorderLayout.SOUTH, new Label("South")).
add(BorderLayout.NORTH, new Label("North")).
add(BorderLayout.EAST, new Label("East")).
add(BorderLayout.WEST, new Label("West"));

hi.show();

Results in:

Figure 2.16. Border Layout with CENTER_BEHAVIOR_CENTER

24

Because of its scaling behavior scrolling a border layout makes no

sense. However it is a common mistake to apply a border layout to a
scrollable container or trying to make a border layout scrollable. That
is why Container explicitly blocks scrolling on a border layout.

RTL = Right To Left or Bidi = bi-directional. A common term used for languages such as Hebrew or

Arabic that are written from the right to left direction hence all the UI needs to be "reversed". Bidi denotes
the fact that while the language is written from right to left, the numbers are still written in the other
direction hence two directions

52

Basics: Themes, Styles, Components & Layouts

In the case of RTL
in this image:

24

the EAST and WEST values are implicitly reversed as shown

Figure 2.17. Border Layout in RTL mode

The preferred size of the center component doesnt matter in border
layout but the preferred size of the sides is. E.g. If you place an very
large component in the SOUTH it will take up the entire screen and
wont leave room for anything.

2.4.6.Grid Layout
25

GridLayout accepts a predefined grid (rows/columns) and grants all components

within it an equal size based on the dimensions of the largest component.
The main use case for this layout is a grid of icons e.g. like one would
see in the iPhone home screen.
If the number of rows * columns is smaller than the number of components added a
new row is implicitly added to the grid. However, if the number of components is smaller
than available cells (wont fill the last row) blank spaces will be left in place.
25

https://www.codenameone.com/javadoc/com/codename1/ui/layouts/GridLayout.html

53

Basics: Themes, Styles, Components & Layouts

In this example we can see that a 2x2 grid is used to add 5 elements, this results in an
additional row thats implicitly added turning the grid to a 3x2 grid implicitly and leaving
one blank cell.
Form hi = new Form("Grid Layout 2x2", new GridLayout(2, 2));
hi.add(new Label("First")).

add(new Label("Second")).
add(new Label("Third")).

add(new Label("Fourth")).
add(new Label("Fifth"));

Figure 2.18. Grid Layout 2x2

54

Basics: Themes, Styles, Components & Layouts

When we use a 2x4 size ratio we would see elements getting cropped as we do
here. The grid layout uses the grid size first and doesnt pay too much attention to the
preferred size of the components it holds.

Figure 2.19. Grid Layout 2x4

Grid also has an autoFit attribute that can be used to automatically calculate the column
count based on available space and preferred width. This is really useful for working
with UIs where the device orientation might change.

55

Basics: Themes, Styles, Components & Layouts

There is also a terse syntax for working with a grid that has two versions, one that uses
the "auto fit" option and another that accepts the column names. Heres a sample of the
terse syntax coupled with the auto fit screenshots of the same code in two orientations:
GridLayout.encloseIn(new Label("First"),
new Label("Second"),
new Label("Third"),

new Label("Fourth"),

new Label("Fifth")));

Figure 2.20. Grid Layout autofit portrait

56

Basics: Themes, Styles, Components & Layouts

Figure 2.21. Grid Layout autofit landscape

2.4.7.Table Layout
26

The TableLayout is a very elaborate constraint based layout manager that can
arrange elements in rows/columns while defining constraints to control complex
behavior such as spanning, alignment/weight etc.
The table layout is in the com.codename1.ui.table package
and not in the layouts package.
This is due to the fact that TableLayout was originally designed
27
for the Table class.
Despite being constraint based the table layout isnt strict about constraints and will
implicitly add a constraint when one is missing.
Unlike grid layout table layout wont implicitly add a row if the row/
column count is incorrect

Form hi = new Form("Table Layout 2x2", new TableLayout(2, 2));

26
27

https://www.codenameone.com/javadoc/com/codename1/ui/table/TableLayout.html
https://www.codenameone.com/javadoc/com/codename1/ui/table/Table.html

57

Basics: Themes, Styles, Components & Layouts

hi.add(new Label("First")).

add(new Label("Second")).
add(new Label("Third")).

add(new Label("Fourth")).
add(new Label("Fifth"));

hi.show();

Figure 2.22. 2x2 TableLayout with 5 elements, notice that the last
element is missing
Table layout supports the ability to grow the last column which can be enabled using
the setGrowHorizontally method. You can also use a shortened terse syntax to
58

Basics: Themes, Styles, Components & Layouts

construct a table layout however since the table layout is a constraint based layout you
wont be able to utilize its full power with this syntax.
The default usage of the encloseIn below uses the setGrowHorizontally flag.
Container tl = TableLayout.encloseIn(2, new Label("First"),
new Label("Second"),
new Label("Third"),

new Label("Fourth"),

new Label("Fifth")));

Figure 2.23. TableLayout.encloseIn() with default behavior of

growing the last column

The Full Potential

Table layout is a beast, to truly appreciate it we need to use the constraint syntax which
allows us to span, align and set width/height for the rows & columns.

59

Basics: Themes, Styles, Components & Layouts

28

Table layout works with a Constraint instance that can communicate our intentions
into the layout manager. Such constraints can include more than one attribute e.g. span
and height.
Table layout constraints cant be reused for more than one
component.
The constraint class supports the following attributes

Table 2.1. Constraint properties

column

The column for the table cell. This

defaults to -1 which will just place the
component in the next available cell

row

Similar to column, defaults to -1 as well

width

The column width in percentages, -1 will

use the preferred size. -2 for width will
take up the rest of the available space

height

Similar to width but doesnt support the

-2 value

spanHorizontal

The cells that should be occupied

horizontally defaults to 1 and cant
exceed the column count - current offset.

spanVertical

Similar to spanHorizontal with the same

limitations

horizontalAlign

The horizontal alignment of the

content within the cell, defaults
to the special case -1 value to
take up all the cell space can be
either -1 , Component.LEFT ,
Component.RIGHT or
Component.CENTER

verticalAlign

Similar to horizontalAlign can be

one of -1 , Component.TOP ,
Component.BOTTOM or
Component.CENTER

28

https://www.codenameone.com/javadoc/com/codename1/ui/table/TableLayout.Constraint.html

60

Basics: Themes, Styles, Components & Layouts

You only need to set width / height to one cell in a column/row.

The table layout constraint sample tries to demonstrate some of the unique things you
can do with constraints.
Due to the complexity of the code below we annotate lines with
numbers and follow up on individual lines.

TableLayout tl = new TableLayout(2, 3);

Form hi = new Form("Table Layout Cons", tl);

hi.setScrollable(false);
hi.add(tl.createConstraint().
widthPercentage(20),

new Label("AAA")).

add(tl.createConstraint().
horizontalSpan(2).
heightPercentage(80).
verticalAlign(Component.CENTER).
horizontalAlign(Component.CENTER),
new Label("Span H")).

add(new Label("BBB")).
add(tl.createConstraint().
widthPercentage(60).
heightPercentage(20),
new Label("CCC")).

add(tl.createConstraint().
widthPercentage(20),
new Label("DDD"));

We need the table layout instance to create constraints. A constraint must be

created for every component and must be used with the same layout as the parent
container.
This is rather important. To get the look in the screenshot we need to turn scrolling
off so the height constraint doesnt take up available height. Otherwise it will
miscalculate available height due to scrolling. You can scroll a table layout but
sizing will be different.
61

Basics: Themes, Styles, Components & Layouts

We create the constraint and instantly apply width to it. This is a shorthand syntax
for the code block below
We can chain constraint creation using a call like this so multiple constraints apply
to a single cell. Notice that we dont span and set width on the same axis (horizontal
span + width), doing something like that would create confusing behavior.
Here is the full code mentioned in item 3:
TableLayout.Constraint cn = tl.createConstraint();
cn.setWidthPercentage(20);
hi.add(cn, new Label("AAA")).

Figure 2.24. TableLayout constraints can be used to create very el

2.4.8.Layered Layout
29

The LayeredLayout places the components in order one on top of the other and
sizes them all to the size of the largest component. This is useful when trying to create
an overlay on top of an existing component. E.g. an x button to allow removing the
component.
29

https://www.codenameone.com/javadoc/com/codename1/ui/layouts/LayeredLayout.html

62

Basics: Themes, Styles, Components & Layouts

Figure 2.25. The X on this button was placed there using the layered
layout code below
The code to generate this UI is slightly complex and contains very little relevant pieces.
The only truly relevant piece is this block:
hi.add(LayeredLayout.encloseIn(settingsLabel,
FlowLayout.encloseRight(close)));

We are doing three distinct things here:

1. We are adding a layered layout to the form.
63

Basics: Themes, Styles, Components & Layouts

2. We are creating a layered layout and placing two components within. This would be
30
31
the equivalent of just creating a LayeredLayout Container and invoking add
twice.

3. We use FlowLayout

32

to position the X close button in the right position.

The layered layout sizes all components to the exact same size one
on top of the other. It usually requires that we use another container
within; in order to position the components correctly.
This is the full source of the example for completeness:
Form hi = new Form("Layered Layout");

int w = Math.min(Display.getInstance().getDisplayWidth(),
Display.getInstance().getDisplayHeight());

Button settingsLabel = new Button("");

Style settingsStyle = settingsLabel.getAllStyles();

settingsStyle.setFgColor(0xff);
settingsStyle.setBorder(null);
settingsStyle.setBgColor(0xff00);
settingsStyle.setBgTransparency(255);
settingsStyle.setFont(settingsLabel.getUnselectedStyle().getFont().derive(w / 3,
Font.STYLE_PLAIN));
FontImage.setMaterialIcon(settingsLabel, FontImage.MATERIAL_SETTINGS);
Button close = new Button("");

close.setUIID("Container");
close.getAllStyles().setFgColor(0xff0000);
FontImage.setMaterialIcon(close, FontImage.MATERIAL_CLOSE);
hi.add(LayeredLayout.encloseIn(settingsLabel,
FlowLayout.encloseRight(close)));

Forms have a built in layered layout that you can access via getLayeredPane() ,
this allows you to overlay elements on top of the content pane.
The layered pane is used internally by components such as InteractionDialog
34
AutoComplete etc.
30

https://www.codenameone.com/javadoc/com/codename1/ui/layouts/LayeredLayout.html
31
https://www.codenameone.com/javadoc/com/codename1/ui/Container.html
32
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/FlowLayout.html
33
https://www.codenameone.com/javadoc/com/codename1/components/InteractionDialog.html
34
https://www.codenameone.com/javadoc/com/codename1/ui/AutoCompleteTextField.html

64

33

Basics: Themes, Styles, Components & Layouts

Codename One also includes a GlassPane that resides on top of the
layered pane. Its useful if you just want to "draw" on top of elements
but is harder to use than layered pane.
Placing native widgets within a layered layout is problematic due
to the behavior of peer components. Sample of peer components
35
include the BrowserComponent , video playback etc.
We discuss peer components in the advanced topics section.

2.4.9.GridBag Layout
36

GridBagLayout was introduced to simplify the process of porting existing Swing/AWT

code with a more familiar API. The API for this layout is problematic as it was designed
for AWT/Swing where styles were unavailable. As a result it has its own insets API
instead of using elements such as padding/margin.
Our recommendation is to use Table which is just as powerful but has better Codename
One integration.
To demonstrate grid bag layout we ported the sample from the Java tutorial
Codename One.
Button button;

hi.setLayout(new GridBagLayout());

GridBagConstraints c = new GridBagConstraints();

//natural height, maximum width

c.fill = GridBagConstraints.HORIZONTAL;

button = new Button("Button 1");

c.weightx = 0.5;
c.fill = GridBagConstraints.HORIZONTAL;
c.gridx = 0;
c.gridy = 0;
hi.addComponent(c, button);
button = new Button("Button 2");

c.fill = GridBagConstraints.HORIZONTAL;
c.weightx = 0.5;
35
36
37

https://www.codenameone.com/javadoc/com/codename1/ui/BrowserComponent.html
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/GridBagLayout.html
http://docs.oracle.com/javase/tutorial/uiswing/layout/gridbag.html

65

37

to

Basics: Themes, Styles, Components & Layouts

c.gridx = 1;

c.gridy = 0;
hi.addComponent(c, button);
button = new Button("Button 3");

c.fill = GridBagConstraints.HORIZONTAL;
c.weightx = 0.5;
c.gridx = 2;
c.gridy = 0;
hi.addComponent(c, button);
button = new Button("Long-Named Button 4");
c.fill = GridBagConstraints.HORIZONTAL;
c.ipady = 40;

//make this component tall

c.weightx = 0.0;
c.gridwidth = 3;
c.gridx = 0;
c.gridy = 1;
hi.addComponent(c, button);
button = new Button("5");

c.fill = GridBagConstraints.HORIZONTAL;
c.ipady = 0;

c.weighty = 1.0;

//reset to default

//request any extra vertical space

c.anchor = GridBagConstraints.PAGE_END; //bottom of space

c.insets = new Insets(10,0,0,0);

//top padding

c.gridx = 1;

//aligned with button 2

c.gridy = 2;

//third row

c.gridwidth = 2;

//2 columns wide

hi.addComponent(c, button);

Notice that because of the way gridbag works we didnt provide any terse syntax API
for it although it should be possible.

66

Basics: Themes, Styles, Components & Layouts

Figure 2.26. GridbagLayout sample from the Java tutorial running

on Codename One

2.4.10.Group Layout
38

GroupLayout is a layout that would be familiar to the users of the NetBeans GUI
39
builder (Matisse) . Its a layout manager thats really hard to use for manual coding
but is remarkably powerful for some really elaborate use cases.
It was originally added during the LWUIT days as part of an internal attempt to port
Matisse to LWUIT. It is still useful to this day as developers copy and paste Matisse
code into Codename One and produce very elaborate layouts with drag & drop.
Since the layout is based on an older version of group layout some things need to be
adapted in the code or you should use the special "compatibility" library for Matisse to
get better interaction. We also recommend tweeking Matisse to use import statements
instead of full package names, that way if you use Label just changing the awt import
40
to a Codename One import will make it use Label .
38
39
40

https://www.codenameone.com/javadoc/com/codename1/ui/layouts/GroupLayout.html
https://netbeans.org/features/java/swing.html
https://www.codenameone.com/javadoc/com/codename1/ui/Label.html

67

Basics: Themes, Styles, Components & Layouts

Unlike any other layout manager group layout adds the components into the container
instead of the standard API. This works nicely for GUI builder code but as you can see
from this sample it doesnt make the code very readable:
Form hi = new Form("GroupLayout");
Label label1 = new Label();
Label label2 = new Label();
Label label3 = new Label();
Label label4 = new Label();
Label label5 = new Label();
Label label6 = new Label();
Label label7 = new Label();
label1.setText("label1");
label2.setText("label2");
label3.setText("label3");
label4.setText("label4");
label5.setText("label5");
label6.setText("label6");
label7.setText("label7");
GroupLayout layout = new GroupLayout(hi.getContentPane());
hi.setLayout(layout);
layout.setHorizontalGroup(
layout.createParallelGroup(GroupLayout.LEADING)

.add(layout.createSequentialGroup()
.addContainerGap()
.add(layout.createParallelGroup(GroupLayout.LEADING)
.add(layout.createSequentialGroup()
.add(label1, GroupLayout.PREFERRED_SIZE,
GroupLayout.DEFAULT_SIZE, GroupLayout.PREFERRED_SIZE)
.addPreferredGap(LayoutStyle.RELATED)
.add(layout.createParallelGroup(GroupLayout.LEADING)
.add(label4, GroupLayout.PREFERRED_SIZE,
GroupLayout.DEFAULT_SIZE, GroupLayout.PREFERRED_SIZE)
.add(label3, GroupLayout.PREFERRED_SIZE,
GroupLayout.DEFAULT_SIZE, GroupLayout.PREFERRED_SIZE)

68

Basics: Themes, Styles, Components & Layouts

.add(label2, GroupLayout.PREFERRED_SIZE,

GroupLayout.DEFAULT_SIZE, GroupLayout.PREFERRED_SIZE)))
.add(label5, GroupLayout.PREFERRED_SIZE,
GroupLayout.DEFAULT_SIZE, GroupLayout.PREFERRED_SIZE)

.add(layout.createSequentialGroup()
.add(label6, GroupLayout.PREFERRED_SIZE,
GroupLayout.DEFAULT_SIZE, GroupLayout.PREFERRED_SIZE)
.addPreferredGap(LayoutStyle.RELATED)
.add(label7, GroupLayout.PREFERRED_SIZE,
GroupLayout.DEFAULT_SIZE, GroupLayout.PREFERRED_SIZE)))
.addContainerGap(296, Short.MAX_VALUE))
);
layout.setVerticalGroup(
layout.createParallelGroup(GroupLayout.LEADING)
.add(layout.createSequentialGroup()
.addContainerGap()
.add(layout.createParallelGroup(GroupLayout.TRAILING)

.add(label2, GroupLayout.PREFERRED_SIZE,
GroupLayout.DEFAULT_SIZE, GroupLayout.PREFERRED_SIZE)
.add(label1, GroupLayout.PREFERRED_SIZE,
GroupLayout.DEFAULT_SIZE, GroupLayout.PREFERRED_SIZE))
.addPreferredGap(LayoutStyle.RELATED)
.add(label3, GroupLayout.PREFERRED_SIZE, GroupLayout.DEFAULT_SIZE,
GroupLayout.PREFERRED_SIZE)
.addPreferredGap(LayoutStyle.RELATED)
.add(label4, GroupLayout.PREFERRED_SIZE, GroupLayout.DEFAULT_SIZE,
GroupLayout.PREFERRED_SIZE)
.addPreferredGap(LayoutStyle.RELATED)
.add(label5, GroupLayout.PREFERRED_SIZE, GroupLayout.DEFAULT_SIZE,
GroupLayout.PREFERRED_SIZE)
.addPreferredGap(LayoutStyle.RELATED)
.add(layout.createParallelGroup(GroupLayout.LEADING)
.add(label6, GroupLayout.PREFERRED_SIZE,
GroupLayout.DEFAULT_SIZE, GroupLayout.PREFERRED_SIZE)
.add(label7, GroupLayout.PREFERRED_SIZE,
GroupLayout.DEFAULT_SIZE, GroupLayout.PREFERRED_SIZE))
.addContainerGap(150, Short.MAX_VALUE))
);

69

Basics: Themes, Styles, Components & Layouts

Figure 2.27. GroupLayout Matisse generated UI running in

Codename One
If you are porting newer Matisse code there are simple changes you can do:
Change addComponent to add
Change addGroup to add
Remove references to ComponentPlacement and reference LayoutStyle
directly

70

Basics: Themes, Styles, Components & Layouts

2.4.11.Mig Layout
MigLayout

41

is a popular cross platform layout manager that was ported to Codename

One from Swing.

MiG is still considered experimental so proceed with caution!
The API was deprecated to serve as a warning of its experimental
status.
The best reference for MiG would probably be its quick start guide (PDF link)
reference we ported one of the samples from that PDF to Codename One:

42

. As a

Form hi = new Form("MigLayout", new MigLayout("fillx,insets 0"));

hi.add(new Label("First")).

add("span 2 2", new Label("Second")).

cells.

add("wrap", new Label("Third")).

// The component will span 2x2

// Wrap to next row

add(new Label("Forth")).

add("wrap", new Label("Fifth")).

// Note that it "jumps over" the

occupied cells.

add(new Label("Sixth")).

add(new Label("Seventh"));

hi.show();

41
42

https://www.codenameone.com/javadoc/com/codename1/ui/layouts/mig/MigLayout.html
http://www.miglayout.com/QuickStart.pdf

71

Basics: Themes, Styles, Components & Layouts

Figure 2.28. MiG layout sample ported to Codename One

It should be reasonably easy to port MiG code but you should notice the following:
MiG handles a lot of the spacing/padding/margin issues that are missing in Swing/
AWT. With Codename One styles we have the padding & margin which are probably
a better way to do a lot of the things that MiG does
The add method in Codename One can be changed as shown in the sample
above.
The constraint argument for Coedname One add calls appears before the
Component instance.
72

Basics: Themes, Styles, Components & Layouts

2.5.GUI Builder
The GUI builder allows us to arrange components visually within a UI using drag & drop,
property sheets etc. With the GUI builder we can create elaborate, rich UIs without
writing the layout code.
The new GUI builder is still in beta state at this time, it shouldnt be
confused with the old GUI builder that is a part of the Codename
One designer tool

Why two GUI Builders?

The original old GUI builder has its roots in our work at Sun Microsystems, it
was developed directly into the designer tool and stores its data as part of the
resource file. When creating an application for the old GUI builder you must
define it as a "visual application" which will make it use the old GUI builder.
The roots of this GUI builder are pretty old. When we initially built it we still had
to support feature phones with 2mb of RAM and the iPad wasnt announced yet.
Due to that we picked an architecture that made sense for those phones with a
greater focus on navigation and resource usage. Newer mobile applications are
rivaling desktop applications in complexity and in those situations the old GUI
builder doesnt make as much sense
The old GUI builder is in the designer tool, its a Swing application that includes
the theme design etc.
It generates a Statemachine class that contains all the main user GUI
interaction code.

The new GUI builder is a standalone application that you launch from the right
click menu by selecting a form as explained below. Here are screenshots of both
to help you differentiate:

73

Basics: Themes, Styles, Components & Layouts

Figure 2.29. The old GUI builder

Figure 2.30. The same UI in the new GUI builder

74

Basics: Themes, Styles, Components & Layouts

2.5.1.Hello World
Creating a hello world app in the new GUI builder is actually pretty trivial, you need to
start with a regular handcoded application. Not a GUI builder application as it refers
to the old GUI builder!
Creating a new hello world is similar for all IDEs and is covered in all the getting started
tutorials for the various IDEs specifically in NetBeans

43

, IntelliJ

44

& Eclipse

45

The new GUI builder requires Java 8. This means the IDE itself
needs to run on top of Java 8!
Following are the instructions for creating a form and launching the GUI builder. While
they are similar there are minor IDE differences. Usage of the GUI builder is identical
in all IDEs as the GUI builder is a separate application.

NetBeans
In NetBeans you need to follow these 4 steps:

Figure 2.31. Right click the package select New Other

43

http://www.codenameone.com/how-do-i---create-a-basic-hello-world-applicationsend-it-to-my-deviceusing-netbeans.html
44
http://www.codenameone.com/how-do-i---create-a-basic-hello-world-applicationsend-it-to-my-deviceusing-intellij-idea.html
45
http://www.codenameone.com/how-do-i---create-a-basic-hello-world-applicationsend-it-to-my-deviceusing-eclipse.html

75

Basics: Themes, Styles, Components & Layouts

Figure 2.32. In the Codename One section select the GUI builder
form

Figure 2.33. Type in the name of the form and click finish, you can
change the type to be a Container or Dialog
76

Basics: Themes, Styles, Components & Layouts

Figure 2.34. Launch the GUI builder thru the right click menu on the
newly created file

IntelliJ/IDEA
In IntelliJ you need to follow these 3 steps:

Figure 2.35. Right click the package select New Codename One
Form (or Dialog/Container)

Figure 2.36. Type in a name for the new form

77

Basics: Themes, Styles, Components & Layouts

Figure 2.37. Launch the GUI builder thru the right click menu on the
newly created file

Eclipse
In Eclipse you need to follow these 4 steps:

Figure 2.38. Right click the package select New Other

78

Basics: Themes, Styles, Components & Layouts

Figure 2.39. In the Codename One section select the GUI builder
option

79

Basics: Themes, Styles, Components & Layouts

Figure 2.40. Type in the name of the form and click finish, you can
change the type to be a Container or Dialog

Figure 2.41. Launch the GUI builder thru the right click menu on the
newly created file

Basic Usage
Notice that the UI of the new GUIBuilder might change in various ways but the basic
concepts should remain the same.

80

Basics: Themes, Styles, Components & Layouts

The GUI builder is controlled via its main toolbar, notice that your changes will only be
applied when you click the Save button on the right:

Figure 2.42. The features of the main toolbar

The sidebar includes the functionality we will be working with most of the time:

Figure 2.43. The sidebar options

Well start by selecting the Component Palette and dragging a button into the UI:

81

Basics: Themes, Styles, Components & Layouts

Figure 2.44. You can drag any component you want from the
sidebar to the main UI
You can then re-arrange the order of the components but since they use the default
FlowLayout you cant position them anywhere you want. Well discuss arrangement
and layout managers in the GUI builder below.
You should have a UI that looks like this when you select the button you placed, it
shows the properties that you can modify and the events that you can bind:

Figure 2.45. Properties allow you to customize everything about a

component

82

Basics: Themes, Styles, Components & Layouts

You can edit any property by clicking it, this launches the appropriate UI. E.g. for image
properties you will be presented with an image dialog that allows you to pick an image
from the resource file:

Figure 2.46. You can edit properties such as the icon property by
clicking it, this opens the image selection dialog
You can add an image to the resource file using the designer tool
46
as covered in this video
For things like setting the text on the component we can use a convenient "long click"
on the component to edit the text in place as such:

Figure 2.47. Use the long click to edit the text "in place"
46

http://www.codenameone.com/how-do-i---fetch-an-image-from-the-resource-file---add-a-

multiimage.html

83

Basics: Themes, Styles, Components & Layouts

Events
When a component supports broadcasting events you can bind such events by
selecting it, then selecting the events tab and clicking the button matching the event
type

Figure 2.48. The events tab is listed below supported event types
can be bound above
Once an event is bound the IDE will open to the event code e.g.:

84

Basics: Themes, Styles, Components & Layouts

public void onButton_1ActionEvent(com.codename1.ui.events.ActionEvent ev)

{

Some IDEs only generate the project source code after you explicitly
build the project so if your code needs to access variables etc. try
building first
Within the code you can access all the GUI components you defined with the gui_
prefix e.g. Button_1 from the UI is represented as:
private com.codename1.ui.Button gui_Button_1 = new
com.codename1.ui.Button();

Layouts
In this section we wont try to discuss layouts in depth as this is a deep and complex
subject. You can read more about the properties of the various Codename One layouts
47
in the developer guide .
In general layouts define the mathematical logic for component positions that we can
then apply to the various resolutions supported by the devices. If we didnt have layouts
the UI wouldnt fit on the multitude of devices where it should work. You can nest layouts
by placing containers within the UI and giving any container a different layout manager,
this allows you to construct very elaborate layouts.
You can pick a layout manager using this UI:

47

https://www.codenameone.com/manual/basics.html

85

Basics: Themes, Styles, Components & Layouts

Figure 2.49. Layouts can be picked via the GUI builder UI

Most layouts support settings that allow you to configure their behavior, e.g.
FlowLayout supports settings such as these that allow you to align the components
within it to various locations:

86

Basics: Themes, Styles, Components & Layouts

Figure 2.50. FlowLayout settings

BorderLayout & TableLayout support constraints that allow you to provide
additional hints about the components within the layout:

87

Basics: Themes, Styles, Components & Layouts

Figure 2.51. Border layout constraints

Mixing these layouts in a hierarchy allows you to produce most UIs.
E.g. one of the most powerful tricks in the new GUI builder is the multi selection mode:

Figure 2.52. Multi selection icon

When this mode is turned on the icon turns into a cancel icon to cancel that mode.
When its turned on you can select multiple components and perform operations on all
of them such as changing a property on multiple components or enclosing them in a
container e.g.:

88

Basics: Themes, Styles, Components & Layouts

Figure 2.53. When we toggle on multi-select mode and select

several components we can then enclose them in a Container

Underlying XML
Saving the project generates an XML file representing the UI into the res directory in
the project, the GUI file is created in a matching hierarchy in the project under the res/
guibuilder directory:

89

Basics: Themes, Styles, Components & Layouts

Figure 2.54. The java and GUI files in the hierarchy

If you refactor (rename or move) the java file its connection with the
GUI file will break. You need to move/rename both
You can edit the GUI file directly but changes wont map into the GUI builder unless
you reopen it. These files should be under version control as they are the main files
that change. The GUI builder file for the button and label code looks like this:
<?xml version="1.0" encoding="UTF-8"?>

<component type="Form" layout="FlowLayout" flowLayoutFillRows="false" flowLayoutAlign="1

title="My new title" name="MyForm">
<component type="Button" text="Button" name="Button_1" actionEvent="true">
</component>
<component type="Label" text="Hi World" name="Label_1">
</component>

90

Basics: Themes, Styles, Components & Layouts

</component>

This format is relatively simple and is roughly the same format used by the old GUI
builder which makes the migration to the new GUI builder possible. This file triggers
the following Java source file:
package com.mycompany.myapp;
/**
* GUI builder created Form
*
* @author shai
*/
public class MyForm extends com.codename1.ui.Form {
public MyForm() {
}

this(com.codename1.ui.util.Resources.getGlobalResources());

public MyForm(com.codename1.ui.util.Resources resourceObjectInstance)

initGuiBuilderComponents(resourceObjectInstance);

//-- DON'T EDIT BELOW THIS LINE!!!

private com.codename1.ui.Label gui_Label_1 = new

com.codename1.ui.Label();

private com.codename1.ui.Button gui_Button_1 = new

com.codename1.ui.Button();

// <editor-fold defaultstate="collapsed" desc="Generated Code">

private void guiBuilderBindComponentListeners() {

EventCallbackClass callback = new EventCallbackClass();

gui_Button_1.addActionListener(callback);

class EventCallbackClass implements

com.codename1.ui.events.ActionListener,
com.codename1.ui.events.DataChangedListener {

private com.codename1.ui.Component cmp;

public EventCallbackClass(com.codename1.ui.Component cmp) {

}

this.cmp = cmp;

91

Basics: Themes, Styles, Components & Layouts

public EventCallbackClass() {
}

ev) {

public void actionPerformed(com.codename1.ui.events.ActionEvent

com.codename1.ui.Component sourceComponent =
ev.getComponent();

if(sourceComponent.getParent().getLeadParent() != null) {

sourceComponent =
sourceComponent.getParent().getLeadParent();
}

if(sourceComponent == gui_Button_1) {

onButton_1ActionEvent(ev);

public void dataChanged(int type, int index) {

}

private void initGuiBuilderComponents(com.codename1.ui.util.Resources

resourceObjectInstance) {
guiBuilderBindComponentListeners();

setLayout(new com.codename1.ui.layouts.FlowLayout());
setTitle("My new title");
setName("MyForm");
addComponent(gui_Label_1);
addComponent(gui_Button_1);
gui_Label_1.setText("Hi World");
gui_Label_1.setName("Label_1");
gui_Button_1.setText("Click Me");
gui_Button_1.setName("Button_1");

}// </editor-fold>

//-- DON'T EDIT ABOVE THIS LINE!!!

public void onButton_1ActionEvent(com.codename1.ui.events.ActionEvent

ev) {
}
}

Dont touch the code within the DONT EDIT comments

92

Basics: Themes, Styles, Components & Layouts

The GUI builder uses the "magic comments" approach where code is generated into
those areas to match the XML defined in the GUI builder. Various IDEs generate that
code at different times. Some will generate it when you run the app while others will
generate it as you save the GUI in the builder.
You can write code freely within the class both by using the event mechanism, by writing
code in the constructors or thru overriding functionality in the base class.

93

Chapter3.Theme Basics
This chapter covers the creation of a simple hello world style theme and its visual
customization. It uses the Codename One Designer tool to demonstrate basic concepts
in theme creation such as 9-piece borders, selectors and style types.

3.1.Understanding Codename One Themes

Codename One themes are pluggable CSS like elements that allow developers to
determine/switch the look of the application in runtime. A theme can be installed via
1
the UIManager class and themes can be layered one on top of the other (like CSS).
By default, Codename One themes derive the native operating system themes,
although this behavior is entirely optional.
2

A theme initializes the Style objects, which are then used by the components to render
3
4
themselves or by the LookAndFeel & DefaultLookAndFeel classes to create the
appearance of the application.
Codename One themes have some built-in defaults, e.g. borders for buttons and
padding/margin/opacity for various components. These are a set of common sense
defaults that can be overridden within the theme.
5

Codename One themes are effectively a set of UIIDs mapped to a Style object.
Codename One applications always have a theme, you can modify it to suit your needs
and you can add multiple themes within the main resource file.
You can also add multiple resource files to a project and work with them. In code a
theme is initialized using this code in your main class:
private Resources theme;
public void init(Object context) {
}

theme = UIManager.initFirstTheme("/theme");

https://www.codenameone.com/javadoc/com/codename1/ui/plaf/UIManager.html
2
https://www.codenameone.com/javadoc/com/codename1/ui/plaf/Style.html
3
https://www.codenameone.com/javadoc/com/codename1/ui/plaf/LookAndFeel.html
4
https://www.codenameone.com/javadoc/com/codename1/ui/plaf/DefaultLookAndFeel.html
5
https://www.codenameone.com/javadoc/com/codename1/ui/plaf/Style.html

94

Theme Basics
The initFirstTheme method is a helper method that hides some try / catch
logic as well as some verbosity. This could be expressed as:
try {

theme = Resources.openLayered("/theme");

UIManager.getInstance().setThemeProps(theme.getTheme(theme.getThemeResourceNames()
[0]));
} catch(IOException e){
}

e.printStackTrace();

In GUI builder application themes get loaded internally by the state machine. You can
override their loading via the initTheme method, this is discussed in the old GUI
builder section.
The paragraph above refers to the old GUI builder. The new GUI
builder which is currently in alpha stages uses the standard manual
application structure.

3.2.Customizing Your Theme

We can launch the designer tool by double clicking on the theme.res file found in
typical Codename One applications. In the left side you can see the section picker and
within it the Theme section.

95

Theme Basics

Figure 3.1. The theme area in the designer

When you select the theme you will see the theme default view.

Figure 3.2. Theme default view

96

Theme Basics
There are several interesting things to notice here the preview section allows us to
instantly see the changes we make to the theme data.

Figure 3.3. Theme preview section

The theme state tabs and constant tabs allow us to pass between the various editing
modes for the theme & also add theme constants.
Well discuss theme constants in-depth soon but styles are probably more important.
Codename One has 4 builtin styles that every component can use:
Unselected - normally this is what you will see when you style a component. This
is the default view of the designer.
97

Theme Basics
Selected - when the component has focus or is being touched you will see this style.
Notice that on touch devices focus is only shown when the screen is touched.
Pressed - only applies to buttons, tabs. Represents the look of a component when
its pressed.
Disabled - used when the developer has invoked setEnabled(false) on the
component. This indicates the component is inaccessible.

Figure 3.4. You can use these tabs to add the various types of styles
and theme constants
The most important section is the style section. It allows us to add/edit/remove style
UIIDs.
Notice the Default Style section, it allows us to customize global defaults for the styles.
Use it with caution as changes here can have wide implications.

98

Theme Basics

Figure 3.5. The theme selection area allows us to add, edit and
delete entries. Notice the default style entry which is a unique
special case
When we add an entry to the style we can just type the desired UIID into the box at
the top of the dialog. We can also pick a UIID from the combo box but that might not
include all potential options.
You can use the Component Inspector tool in the simulator to locate
6
a component and its UIID in a specific Form .

https://www.codenameone.com/javadoc/com/codename1/ui/Form.html

99

Theme Basics

Figure 3.6. When pressing the Add/Edit entry we can edit a specific
style entry UIID
When we add/edit an entry an important piece of the puzzle is the Derive check box that
appears next to all of the UIID entries. All styles derive from the base style and usually
from the native theme defaults, so when this flag is checked the defaults will be used.
When you uncheck that checkbox the fields below it become editable and you can
override the default behavior. To restore the default just recheck that flag.
A common oddity for developers is that when they press Add and
dont derive any entry nothing is actually added. The entries in
the theme are essentially key/value pairs so when you dont add
anything there are no keys so the entry doesnt show up.

3.3.Customizing The Title

The title is a great target for customization since it includes a few interesting
"complexities".
100

Theme Basics
The Title is surrounded by a TitleArea container that encloses it, above the title
you will also see the StatusBar UIID that prevents the status details from drawing
on top of the title text.

Figure 3.7. Title Area UIIDs

The StatusBar UIID is a special case that is only there on iOS. In
iOS the application needs to render the section under the status bar
(which isnt the case for other OSs) and the StatusBar UIID was
added so developers can ignore that behavior.

3.3.1.Background Priorities & Types

A slightly confusing aspects of styles in Codename One is the priorities of backgrounds.
When you define a specific type of background it will override prior definitions, this even
applies to inheritance.
E.g. if the theme defined an image border for the Button UIID (a very common case)
if you will try to define the background image or the background color of Button those
will be ignored!
The solution is to derive the border and select the Empty border
type.
The order for UIID settings for background is as follows:
1. Border - if the component has a border it can override everything. Image borders
always override all background settings you might have.
2. Image - a scaled image background overrides background color/transparency
settings.
101

Theme Basics
3. Background Color/Transparency - If transparency is larger than 0 then this takes
effect.
Gradients sit at a higher position than background color. However,
their performance is abysmal at the time of this writing and we
strongly recommend avoiding their usage.

3.3.2.The Background Behavior & Image

Lets start in the first page of the style entry, well customize the background behavior
for the Title UIID and demonstrate/explain some of the behaviors.
The pictures below demonstrate the different types of background image behaviors.

Figure 3.8. IMAGE_SCALED scales the image without preserving

aspect ratio to fit the exact size of the component

102

Theme Basics

Figure 3.9. IMAGE_SCALED_FILL scales the image while

preserving aspect ratio so it fills the entire space of the component
Aspect ratio is the ratio between the width and the right of the image.
E.g. if the image is 100x50 pixels and we want the width to be
200 pixels preserving the aspect ratio will require the height to also
double to 200x100 .
We highly recommend preserving the aspect ratio to keep images
more "natural".

Figure 3.10. IMAGE_SCALED_FIT scales the image

preserving aspect ratio so it fits within the component
103

while

Theme Basics

Figure 3.11. IMAGE_TILE_BOTH tiles the image on both axis of the

component

Figure 3.12. IMAGE_TILE_VERTICAL_ALIGN_LEFT tiles the image

on the left side of the component

104

Theme Basics

Figure 3.13. IMAGE_TILE_VERTICAL_ALIGN_CENTER tiles the

image in the middle of the component

Figure 3.14. IMAGE_TILE_VERTICAL_ALIGN_RIGHT tiles the image

on the right side of the component

105

Theme Basics

Figure 3.15. IMAGE_TILE_HORIZONTAL_ALIGN_TOP tiles the

image on the top of the component

Figure 3.16. IMAGE_TILE_HORIZONTAL_ALIGN_CENTER tiles the

image in the middle of the component

106

Theme Basics

Figure 3.17. IMAGE_TILE_HORIZONTAL_ALIGN_BOTTOM tiles the

image to the bottom of the component

Figure 3.18. IMAGE_ALIGNED_TOP places the image centered at

the top part of the component

107

Theme Basics

Figure 3.19. IMAGE_ALIGNED_BOTTOM places the image centered

at the bottom part of the component

Figure 3.20. IMAGE_ALIGNED_LEFT places the image centered at

the left part of the component

108

Theme Basics

Figure 3.21. IMAGE_ALIGNED_RIGHT places the image centered at

the right part of the component

Figure 3.22. IMAGE_ALIGNED_TOP_LEFT places the image at the

top left corner

109

Theme Basics

Figure 3.23. IMAGE_ALIGNED_TOP_RIGHT places the image at the

top right corner

Figure 3.24. IMAGE_ALIGNED_BOTTOM_LEFT places the image at

the bottom left corner

110

Theme Basics

Figure 3.25. IMAGE_ALIGNED_BOTTOM_RIGHT places the image

at the bottom right corner

Figure 3.26. IMAGE_ALIGNED_CENTER places the image in the

middle of the component
The UI also supports setting gradients but we recommend that you
avoid using them as they are less portable than images/borders and
perform poorly.

111

Theme Basics

3.3.3.The Color Settings

The color settings are much simpler than the background behavior. As explained above
the priority for color is at the bottom so if you have a border, image or gradient defined
the background color settings will be ignored.

Figure 3.27. Add theme entry color settings

There are three color settings:
Foreground color is the RRGGBB color that sets the style foreground color normally
used to draw the text of the component. You can use the color picker button on the
side to pick a color
Background same as foreground only determines the background color of the
component
Transparency represents the opacity of the component background as a value
between 0 (transparent) and 255 (opaque)
Setting the background will have no effect unless transparency is
higher than 0. If you dont explicitly define this it might have a different
value based on the native theme

112

Theme Basics

3.3.4.Alignment
Not all component types support alignment and even when they do they dont support it
7

for all elements. E.g. a Label and its subclasses support alignment but will only apply
it to the text and not the icon.
8

Notice that Container doesnt support alignment. You should use the layout manager
to tune component positioning.

Figure 3.28. Alignment of the text within some component types

Aligning text components to anything other than the default
alignment might be a problem if they are editable. The native editing
capabilities might collide with the alignment behavior.

3.3.5.Padding & Margin

Padding and margin are concepts derived from the CSS box model. They are slightly
different in Codename One, where the border spacing is part of the padding, but other
than that they are pretty similar:

7
8

https://www.codenameone.com/javadoc/com/codename1/ui/Label.html
https://www.codenameone.com/javadoc/com/codename1/ui/Container.html

113

Theme Basics

Figure 3.29. Padding & Margin/Box Model

In the above diagram, we can see the component represented in yellow occupying its
preferred size. The padding portion in gray effectively increases the components size.
The margin is the space between components, it allows us to keep whitespace between
multiple components. Margin is represented in red in the diagram.
The theme allows us to customize the padding/margin, and specify them for all 4 sides
of a component. They can be specified in pixels, millimeters/dips, or screen percentage:

Figure 3.30. Padding tab

We recommend using millimeters for all spacing to make it look
good for all device densities. Percentages make sense only in very
extreme cases.

114

Theme Basics

3.3.6.Borders
Borders are a big subject in their own right, the UI for their creation is also a bit
confusing:

Figure 3.31. Border entry in the theme

3.3.7.9-Piece Image Border

The most common border by far is the 9-piece image border, to facilitate that border
type we have a special Image Border Wizard.
A 9 piece image border is a common convention in UI theming that divides a border
into 9 pieces 4 representing corners, 4 representing the sides and one representing
the middle.
Android uses a common variation on the 9-piece border: 9-patch.
The main difference between the 9-piece border & 9-patch is that 9piece borders tile the sides/center whereas 9-patch scales them.
9-piece image borders work better than background images for many use cases where
the background needs to "grow/shrink" extensively and might need to change aspect
ratio.
They dont work well in cases where the image is a-symetric on both axis. E.g. a radial
gradient image. 9-piece images in general dont work very well with complex gradients.
The image border wizard simplifies the process of generating a 9-piece image border
using a 3 stage process.

115

Theme Basics

Figure 3.32. Stage 1: create or pick an image from an existing PNG

file that we will convert to a 9-piece image
Use an image thats designed for a high DPI device e.g. iPhone 6+.

For your convenience you can create a rudimentary image with the create image stage
but for a professional looking application you would usually want to use a design by
a professional designer.

116

Theme Basics

Figure 3.33. Stage 2: Cutting the image and adapting it to the DPIs
The second stage is probably the hardest and most important one in this wizard!
You can change the values of the top/bottom/left/right spinners to move the position of
the guide lines that indicate the various 9 pieces. The image shows the correct cut for
this image type with special attention to the following:
The left/right position is high enough to fit in the rounded corners in their entirety.
Notice that we didnt just leave 1 pixel as that performs badly, we want to leave as
much space as possible!
The top and bottom lines have exactly one pixel between them. This is to avoid
breaking the gradient. E.g. if we set the lines further apart we will end up with this:

Figure 3.34. This is why its important to keep the lines close when
a gradient is involved, notice the tiling effect

117

Theme Basics

Figure 3.35. When the lines are close together the gradient effect
grows more effectively
The elements on the right hand side include the Generate Multi Image options. Here
you can indicate the density of the source image you are using (e.g. if its for iPhone
5 class device pick Very High). You can then select in the checkboxes below the
densities that should be generated automatically for you. This allows fine detail on
the border to be maintained in the various high/low resolution devices.
We go into a lot of details about multi images in the advanced
theming section.

Figure 3.36. Stage 3: Styles to which the border is applied

The last page indicates the styles to which the wizard will apply the border. Under
normal usage you dont really need to touch this as its properly filled out.
You can define the same border for multiple UIIDs from here though.

118

Theme Basics

Border Minimum Size

A common oddity when using the image borders is the fact that even when
padding is removed the component might take a larger size than the height of
the text within it.
The reason for that is the border. Because of the way borders are implemented
they just cant be drawn to be smaller than the sum of their corners. E.g. the
minimum height of a border would be the height of the bottom corner + the height
of the top corner. The minimum width would be the width of the left + right corners.
This is coded into the common preferred size methods in Codename One and
components generally dont shrink below the size of the image border even if
padding is 0.

Customizing The 9-Piece Border

Normally we can just use the 9-piece border wizard but we can also customize the
border by pressing the "" button on the border section in the theme.

Figure 3.37. Press this to customize borders

The UI for the 9-piece border we created above looks like this.
119

Theme Basics

Figure 3.38. 9-piece border in edit mode

You can pick the image represented by every section in the border from the combo
boxes. They are organized in the same way the border is with the 9-pieces placed in
the same position they would occupy when the border is rendered.
Notice that the other elements in the UI are disabled when the image
border type is selected.

3 Image Mode
The 9-piece border has a (rarely used) special case: 3 image mode. In this mode
a developer can specify the top left corner, the top image and the center image to
produce a 9 piece border. The corner and top piece are then rotated dynamically
to produce a standard 9-piece border on the device.
This is useful for reducing application code size but isnt used often as it requires
a more symetric UI.
Dont confuse the 3-image mode for the 9-piece border with
the horizontal/vertical image border below

120

Theme Basics

3.3.8.Horizontal/Vertical Image Border

The 9-piece border is the workhorse of borders in Codename One, however there are
some edge cases of UI elements that should grow on one axis and not on another. A
perfect example of this is the iOS style back button. If we tried to cut it into a 9-piece
border the arrow effect would be broken.

Figure 3.39. Horizontal image border is commonly used for UIs that
cant grow vertically e.g. the iOS style back button
The horizontal and vertical image borders accept 3 images of their respective AXIS
and build the border by placing one image on each side and tiling the center image
between them. E.g. A horizontal border will never grow vertically.
9

In RTL/Bidi modes the borders flip automatically to show the

reverse direction. An iOS style back button will point to the right in
such languages.

Languages that are written from right to left such as Hebrew, Arabic etc.

121

Theme Basics

3.3.9.Empty Border
Empty borders enforce the removal of a border. This is important if you would like to
block a base style from having a border.
10

E.g. Buttons have borders by default. If you would like to create a Button that is
strictly of solid color you could just define the border to be empty and then use the solid
color as you see fit.
There is a null border which is often confused with an empty border.
You should use empty border and not null border.

3.3.10.Bevel/Etched Borders
We generally recommend avoiding bevel/etched border types as they arent as
efficient and look a bit dated in todays applications. We cover them here mostly for
completeness.

Figure 3.40. Bevel border

Figure 3.41. Etched border

3.3.11.Derive
Derive allows us to inherit the behavior of a UIID and extend it with some customization.
10

https://www.codenameone.com/javadoc/com/codename1/ui/Button.html

122

Theme Basics
E.g. Lets say we created a component thats supposed to look like a title, we could do
something like:
cmp.setUIID("Title");

But title might sometimes be aligned to the left (based on theme) and we always want
our component to be center aligned. However, we dont want that to affect the actual
titles in the app
To solve this we can define a MyTitle UIID and derive the Title UIID. Then just
customize that one attribute.

Figure 3.42. Derive title

Issues With Derive

Style inheritance is a problematic topic in every tool that supports such behavior.
Codename One styles start from a global default then have a system default
applied and on top of that have the native OS default applied to them.
At that point a developer can define the style after all of the user settings are
in place. Normally this works reasonably well, but there are some edge cases
where inheriting a style can fail.
When you override an existing style such as Button and choose to derive from
Button in a different selection mode or even a different component altogether
such as Label you might trigger a recursion effect where a theme setting in
the base theme depends on something in a base triggering an infinite loop.
To avoid this always inherit only from UIIDs you defined e.g. MyButton .

123

Theme Basics

3.3.12.Fonts
Codename One currently supports 3 font types:
System fonts - these are very simplistic builtin fonts. They work on all platforms and
come in one of 3 sizes. However, they are ubiquitous and work in every platform
in all languages.
TTF files - you can just place a TTF file in the src directory of the project and it will
appear in the True Type combo box.
Native fonts - these arent supported on all platforms but generally they allow you to
use a set of platform native good looking fonts. E.g. on Android the devices Roboto
font will be used and on iOS Helvetica Neue will be used.
If you use a TTF file MAKE SURE not to delete the file when there
MIGHT be a reference to it. This can cause hard to track down
issues!
Notice that a TTF file must have the ".ttf" extension, otherwise the
build server wont be able to recognize the file as a font and set it up
accordingly (devices need fonts to be defined in very specific ways).
Once you do that, you can use the font from code or from the theme.

Figure 3.43. Font Theme Entry

System fonts are always defined even if you use a TTF or native font.
If the native font/TTF is unavailable in a specific platform the system
font will be used instead.
124

Theme Basics
You can size native/TTF fonts either via pixels, millimeters or based on the size of the
equivalent system fonts:
1. System font size - the truetype font will have the same size as a small, medium
or large system font. This allows the developer to size the font based on the device
DPI.
2. Millimeter size - allows sizing the font in a more DPI aware size.
3. Pixels - useful for some unique cases, but highly problematic in multi-DPI
scenarios.
You should notice that font sizing is very inconsistent between
platforms.
To use fonts from code, you can use:
if(Font.isTrueTypeFileSupported()) {

Font myFont = Font.createTrueTypeFont(fontName, fontFileName);

myFont = myFont.derive(sizeInPixels, Font.STYLE_PLAIN);

// do something with the font

Notice that, in code, only pixel sizes are supported, so its up to you to decide how to
convert that. You also need to derive the font with the proper size, unless you want a
0 sized font which probably isnt very useful.
The font name is the difficult bit, iOS requires the name of the font in order to load the
font. This font name doesnt always correlate to the file name making this task rather
"tricky". The actual font name is sometimes viewable within a font viewer. It isnt always
intuitive, so be sure to test that on the device to make sure you got it right.
due to copyright restrictions we cannot distribute Helvetica and thus
cant simulate it. In the simulator you will see Roboto and not the
device font unless you are running on a Mac.
The code below demonstrates all the major fonts available in Codename One with the
handlee ttf file posing as a standin for arbitrary TTF:
private Label createForFont(Font fnt, String s) {
Label l = new Label(s);

l.getUnselectedStyle().setFont(fnt);
return l;

125

Theme Basics
}
public void showForm() {

GridLayout gr = new GridLayout(5);

gr.setAutoFit(true);

Form hi = new Form("Fonts", gr);

int fontSize = Display.getInstance().convertToPixels(3);
// requires Handlee-Regular.ttf in the src folder root!

Font ttfFont = Font.createTrueTypeFont("Handlee", "HandleeRegular.ttf").

derive(fontSize, Font.STYLE_PLAIN);
Font smallPlainSystemFont = Font.createSystemFont(Font.FACE_SYSTEM,
Font.STYLE_PLAIN, Font.SIZE_SMALL);
Font mediumPlainSystemFont = Font.createSystemFont(Font.FACE_SYSTEM,

Font.STYLE_PLAIN, Font.SIZE_MEDIUM);
Font largePlainSystemFont = Font.createSystemFont(Font.FACE_SYSTEM,
Font.STYLE_PLAIN, Font.SIZE_LARGE);
Font smallBoldSystemFont = Font.createSystemFont(Font.FACE_SYSTEM,
Font.STYLE_BOLD, Font.SIZE_SMALL);
Font mediumBoldSystemFont = Font.createSystemFont(Font.FACE_SYSTEM,
Font.STYLE_BOLD, Font.SIZE_MEDIUM);
Font largeBoldSystemFont = Font.createSystemFont(Font.FACE_SYSTEM,
Font.STYLE_BOLD, Font.SIZE_LARGE);
Font smallItalicSystemFont = Font.createSystemFont(Font.FACE_SYSTEM,
Font.STYLE_ITALIC, Font.SIZE_SMALL);
Font mediumItalicSystemFont = Font.createSystemFont(Font.FACE_SYSTEM,
Font.STYLE_ITALIC, Font.SIZE_MEDIUM);
Font largeItalicSystemFont = Font.createSystemFont(Font.FACE_SYSTEM,
Font.STYLE_ITALIC, Font.SIZE_LARGE);
Font smallPlainMonospaceFont =
Font.createSystemFont(Font.FACE_MONOSPACE, Font.STYLE_PLAIN,
Font.SIZE_SMALL);
Font mediumPlainMonospaceFont =
Font.createSystemFont(Font.FACE_MONOSPACE, Font.STYLE_PLAIN,
Font.SIZE_MEDIUM);
Font largePlainMonospaceFont =
Font.createSystemFont(Font.FACE_MONOSPACE, Font.STYLE_PLAIN,
Font.SIZE_LARGE);
Font smallBoldMonospaceFont = Font.createSystemFont(Font.FACE_MONOSPACE,
Font.STYLE_BOLD, Font.SIZE_SMALL);

126

Theme Basics
Font mediumBoldMonospaceFont =

Font.createSystemFont(Font.FACE_MONOSPACE, Font.STYLE_BOLD,
Font.SIZE_MEDIUM);
Font largeBoldMonospaceFont = Font.createSystemFont(Font.FACE_MONOSPACE,
Font.STYLE_BOLD, Font.SIZE_LARGE);
Font smallItalicMonospaceFont =
Font.createSystemFont(Font.FACE_MONOSPACE, Font.STYLE_ITALIC,
Font.SIZE_SMALL);
Font mediumItalicMonospaceFont =
Font.createSystemFont(Font.FACE_MONOSPACE, Font.STYLE_ITALIC,
Font.SIZE_MEDIUM);
Font largeItalicMonospaceFont =
Font.createSystemFont(Font.FACE_MONOSPACE, Font.STYLE_ITALIC,
Font.SIZE_LARGE);

Font smallPlainProportionalFont =
Font.createSystemFont(Font.FACE_PROPORTIONAL, Font.STYLE_PLAIN,
Font.SIZE_SMALL);
Font mediumPlainProportionalFont =
Font.createSystemFont(Font.FACE_PROPORTIONAL,
Font.SIZE_MEDIUM);
Font largePlainProportionalFont =
Font.createSystemFont(Font.FACE_PROPORTIONAL,
Font.SIZE_LARGE);
Font smallBoldProportionalFont =
Font.createSystemFont(Font.FACE_PROPORTIONAL,
Font.SIZE_SMALL);
Font mediumBoldProportionalFont =
Font.createSystemFont(Font.FACE_PROPORTIONAL,
Font.SIZE_MEDIUM);
Font largeBoldProportionalFont =
Font.createSystemFont(Font.FACE_PROPORTIONAL,
Font.SIZE_LARGE);
Font smallItalicProportionalFont =
Font.createSystemFont(Font.FACE_PROPORTIONAL,
Font.SIZE_SMALL);
Font mediumItalicProportionalFont =
Font.createSystemFont(Font.FACE_PROPORTIONAL,
Font.SIZE_MEDIUM);
Font largeItalicProportionalFont =
Font.createSystemFont(Font.FACE_PROPORTIONAL,
Font.SIZE_LARGE);

Font.STYLE_PLAIN,

Font.STYLE_PLAIN,

Font.STYLE_BOLD,

Font.STYLE_BOLD,

Font.STYLE_BOLD,

Font.STYLE_ITALIC,

Font.STYLE_ITALIC,

Font.STYLE_ITALIC,

String[] nativeFontTypes = {

"native:MainThin", "native:MainLight", "native:MainRegular", "native:MainBold", "nativ

127

Theme Basics

"native:ItalicThin", "native:ItalicLight", "native:ItalicRegular", "native:ItalicBold"

for(String s : nativeFontTypes) {

Font tt = Font.createTrueTypeFont(s, s).derive(fontSize,

Font.STYLE_PLAIN);
hi.add(createForFont(tt, s));
}
hi.add(createForFont(ttfFont, "Handlee TTF Font")).
add(createForFont(smallPlainSystemFont, "smallPlainSystemFont")).
add(createForFont(mediumPlainSystemFont, "mediumPlainSystemFont")).
add(createForFont(largePlainSystemFont, "largePlainSystemFont")).
add(createForFont(smallBoldSystemFont, "smallBoldSystemFont")).
add(createForFont(mediumBoldSystemFont, "mediumBoldSystemFont")).
add(createForFont(largeBoldSystemFont, "largeBoldSystemFont")).
add(createForFont(smallPlainSystemFont, "smallItalicSystemFont")).
add(createForFont(mediumItalicSystemFont, "mediumItalicSystemFont")).
add(createForFont(largeItalicSystemFont, "largeItalicSystemFont")).

add(createForFont(smallPlainMonospaceFont, "smallPlainMonospaceFont")).
add(createForFont(mediumPlainMonospaceFont, "mediumPlainMonospaceFont")).
add(createForFont(largePlainMonospaceFont, "largePlainMonospaceFont")).
add(createForFont(smallBoldMonospaceFont, "smallBoldMonospaceFont")).
add(createForFont(mediumBoldMonospaceFont, "mediumBoldMonospaceFont")).
add(createForFont(largeBoldMonospaceFont, "largeBoldMonospaceFont")).
add(createForFont(smallItalicMonospaceFont, "smallItalicMonospaceFont")).
add(createForFont(mediumItalicMonospaceFont, "mediumItalicMonospaceFont")).
add(createForFont(largeItalicMonospaceFont, "largeItalicMonospaceFont")).

128

Theme Basics

add(createForFont(smallPlainProportionalFont, "smallPlainProportionalFont")).
add(createForFont(mediumPlainProportionalFont, "mediumPlainProportionalFont")).
add(createForFont(largePlainProportionalFont, "largePlainProportionalFont")).
add(createForFont(smallBoldProportionalFont, "smallBoldProportionalFont")).
add(createForFont(mediumBoldProportionalFont, "mediumBoldProportionalFont")).
add(createForFont(largeBoldProportionalFont, "largeBoldProportionalFont")).
add(createForFont(smallItalicProportionalFont, "smallItalicProportionalFont")).
add(createForFont(mediumItalicProportionalFont, "mediumItalicProportionalFont")).
add(createForFont(largeItalicProportionalFont, "largeItalicProportionalFont"));

hi.show();

129

Theme Basics

Figure 3.44. The fonts running on the ipad simulator on a Mac,

notice that this will look different on a PC

130

Theme Basics

Figure 3.45. The same demo running on a OnePlus One device with
Android 5.1

Font Effects
You can define an effect to be applied to a specific font, specifically:
Underline
Strike thru
3d text raised/lowered
3d shadow north
The "3d" effects effectively just draw the text twice, with a sligh offest and two different
colors to create a "3d" feel.
All of the effects are relatively simple and performant.

131

Chapter4.Advanced Theming
This chapter covers the advanced concepts of theming as well as deeper understanding
of how to build/design a Codename One Theme. :icons: font

4.1.Working With UIIDs

UIIDs (User Interface IDentifier) are unique qualifiers given to UI components that
associate a set of theme definitions with a specific set of components. E.g. we can
associate the Button UIID with a component and then define the look for the Button
in the theme.
One of the biggest advantages with UIIDs is the ability to change the UIID of a
component. E.g. to create a multiline label, one can use something like:
TextArea t = ;
t.setUIID("Label");
t.setEditable(false);

This is pretty much how components such as SpanLabel

implemented internally.

are

UIIDs can be customized via the GUI builder and allows for powerful customization of
individual components.
The class name of the component is commonly the same as the
UIID, but they are in essence separate entities.

4.2.Theme Layering
There are two use cases in which you would want to use layering:
You want a slightly different theme in one platform
You want the ability to customize your theme for a specific use case, e.g. let a user
select larger fonts
1

https://www.codenameone.com/javadoc/com/codename1/components/SpanLabel.html

132

Advanced Theming
This is actually pretty easy to do and doesnt require re-doing the entire theme. You can
do something very similar to the cascading effect of CSS where a theme is applied "on
top" of another theme. To do that just add a new theme using the Add Theme button.
Make sure to remove the includeNativeBool constant in the
new theme!
In the new theme define the changes e.g. if you just want a larger default font define
only that property for all the relevant UIIDs and ignore all other properties!
For a non-gui builder app the theme loading looks like this by default:
theme = UIManager.initFirstTheme("/theme");

You should fix it to look like this:

theme = UIManager.initNamedTheme("/theme", "Theme");

This assumes the name of your main theme is "Theme" (not the layer
theme you just added).
The original code relies on the theme being in the 0 position in the theme name array
which might not be the case!
When you want to add the theme layer just use:
UIManager.getInstance().addThemeProps(theme.getTheme("NameOfLayerTheme"));

The addThemeProps call will layer the secondary theme on top of the primary
"Theme" and keep the original UIIDs defined in the "Theme" intact.
If you apply theme changes to a running application you can use Forms
`refreshTheme() to update the UI instantly and provide visual feedback for the
theme changes.

4.3.Override Resources In Platform

When we want to adapt the look of an application to different OS conventions one of the
common requirements is to use different icons. Sometimes we want to change behavior
based on device type e.g. have a different UI structure for a Tablet.
133

Advanced Theming
Codename One allows you to override a resource for a specific platform when doing this
you can redefine a resource differently for that specific platform and also add platform
specific resources.

Figure 4.1. Override resources for specific platform

Overriden resources take precedence over embedded resources thus allowing us
to change the look or even behavior (when overriding a GUI builder element) for a
specific platform/OS.
Overriding the theme is dangerous as a theme has external
dependencies (e.g. image borders). The solution is to use theme
layering and override the layer!
To override select the platform where overriding is applicable

134

Advanced Theming

Figure 4.2. Override for platform, allows us to override the checked

resources and replace them with another resource
You can then click the green checkbox to define that this resource is specific to this
platform. All resources added when the platform is selected will only apply to the
selected platform. If you change your mind and are no longer interested in a particular
override just delete it in the override mode and it will no longer be overridden.

4.4.Theme Constants
The Codename One Designer has a tab for creating constants which can be used
to add global values of various types and behavior hints to Codename One and its
components. Constants are always strings, there are some conventions that allow the
UI to adapt to input various types more easily e.g. if a constant ends with the word Bool it
is treated as a boolean (true/false) value and will be displayed as a checkbox. Similarly
Int will display a numeric picker and Image will show a combo box to pick an image.
The combo box in the designer for adding a theme constant is
editable, you can just type in any value you want!
2

To use a constant one can use the UIManager 's methods to get the appropriate
constant type specifically:
2

https://www.codenameone.com/javadoc/com/codename1/ui/plaf/UIManager.html

135

Advanced Theming
getThemeConstant
isThemeConstant
getThemeImageConstant
Internally, Codename One has several built in constants and the list is constantly
growing. As we add features to Codename One, we try to keep this list up to date but
the very nature of theme constants is "adhoc" and some might not make it here.

Table 4.1. Theme Constants

Constant

Description/Argument

alwaysTensileBool

Enables tensile drag even when there

is no scrolling in the container (only for
scrollable containers)

backGestureThresholdInt

The threshold for the back gesture in the

3
SwipeBackSupport class, defaults to 5

backUsesTitleBool

Indicates to the GUI builder that the

back command should use the title of
the previous form and not just the word
"Back"

defaultCommandImage

Image to give a command with no icon

dialogButtonCommandsBool

Place commands in the dialogs as

buttons

dialogBlurRadiusInt

Sets the default Gaussian blur radius

for the background of the dialogs. The
default value is -1 indicating no blur

dialogPosition

Place the dialog in an arbitrary border

layout position (e.g. North, South,
Center, etc.)

centeredPopupBool

Popup of the combo box will appear in

the center of the screen

changeTabOnFocusBool

Useful for feature phones, allows

changing the tab when the focus
changes immediately, without pressing a
key

https://www.codenameone.com/javadoc/com/codename1/ui/util/SwipeBackSupport.html

136

Advanced Theming
Constant

Description/Argument

checkBoxCheckDisImage

CheckBox image to use instead of

Codename One drawing it on its own

checkBoxCheckedImage

CheckBox image to use instead of

Codename One drawing it on its own

checkBoxOppositeSideBool

Indicates the check box should be drawn

on the opposite side to the text and not
next to the text

checkBoxUncheckDisImage

CheckBox image to use instead of

Codename One drawing it on its own

checkBoxUncheckedImage

CheckBox image to use instead of

Codename One drawing it on its own

comboImage

Combo image to use instead of

Codename One drawing it on its own

commandBehavior

Indicates how commands should act, as

a touch menu, native menu etc. Possible
values: SoftKey, Touch, Bar, Title, Right,
Native

ComponentGroupBool

Enables component group, which allows

components to be logically grouped
together, so the UIIDs of components
would be modified based on their
group placement. This allows for some
unique styling effects where the first/
last elements have different styles from
the rest of the elements. Its disabled by
default, thus leaving its usage up to the
designer

dialogTransitionIn

Default transition for dialog

dialogTransitionInImage

Default transition Image for dialog,

5
causes a Timeline transition effect

dialogTransitionOut

Default transition for dialog

4
5

https://www.codenameone.com/javadoc/com/codename1/ui/Image.html
https://www.codenameone.com/javadoc/com/codename1/ui/animations/Timeline.html

137

Advanced Theming
Constant

Description/Argument

defaultCommandImage

An image to place on a command if

none is defined, only applies to touch
commands

defaultEmblemImage

The emblem painted on the side of the

multibutton, by default this is an arrow on
some platforms

dialogTransitionOutImage

Default transition Image for dialog,

7
causes a Timeline transition effect

disabledColor

Color to use when disabling entries by

default

dlgButtonCommandUIID

The UIID used for dialog button

commands

dlgCommandButtonSizeInt

Minimum size to give to command

buttons in the dialog

dlgCommandGridBool

Places the dialog commands in a grid for

uniform sizes

dlgInvisibleButtons

Includes an RRGGBB color for the line

separating dialog buttons, as is the case
with Android 4 and iOS 7 buttons in

dialogs
dlgSlideDirection

Slide hints

dlgSlideInDirBool

Slide hints

dlgSlideOutDirBool

Slide hints

drawMapPointerBool

Indicates whether a pointer should

appear in the center of the map
component

fadeScrollBarBool

Boolean indicating if the scrollbar should

fade when there is inactivity

fadeScrollEdgeBool

Places a fade effect at the edges of the

screen to indicate that its possible to

6
7

https://www.codenameone.com/javadoc/com/codename1/ui/Image.html
https://www.codenameone.com/javadoc/com/codename1/ui/animations/Timeline.html

138

Advanced Theming
Constant

Description/Argument
scroll until we reach the edge (common
on Android)

fadeScrollEdgeInt

Amount of pixels to fade out at the edge

firstCharRTLBool

Indicates to the
8
GenericListCellRenderer that it should
determine RTL status based on the first
character in the sentence

noTextModeBool

Indicates that the on/off switch in iOS

shouldnt draw text on top of the switch,
which is the case for iOS 7+ but not for
prior versions

fixedSelectionInt

Number corresponding to the fixed

9
selection constants in List

formTransitionIn

Default transition for form

formTransitionInImage

Default transition Image for form,

11
causes a Timeline transition effect

formTransitionOut

Default transition for form

formTransitionOutImage

Default transition Image for form,

13
causes a Timeline transition effect

globalToobarBool

Indicates that the Toolbar API should be

on/off by default for all forms

hideBackCommandBool

Hides the back command from the side

menu when possible

hideEmptyTitleBool

Indicates that a title with no content

should be hidden even if the border for
the title occupies space

hideLeftSideMenuBool

Hides the side menu icon that appears

on the left side of the UI

10

12

8
https://www.codenameone.com/javadoc/com/codename1/ui/list/GenericListCellRenderer.html
9
https://www.codenameone.com/javadoc/com/codename1/ui/List.html
10
https://www.codenameone.com/javadoc/com/codename1/ui/Image.html
11
https://www.codenameone.com/javadoc/com/codename1/ui/animations/Timeline.html
12
https://www.codenameone.com/javadoc/com/codename1/ui/Image.html
13
https://www.codenameone.com/javadoc/com/codename1/ui/animations/Timeline.html

139

Advanced Theming
Constant

Description/Argument

ignorListFocusBool

Hide the focus component of the list

when the list doesnt have focus

infiniteImage

The image used by the infinite progress

component, the component will rotate it
as needed

includeNativeBool

True to derive from the platform native

theme, false to create a blank theme that
only uses the basic defaults

listItemGapInt

Built-in item gap in the list, this defaults

to 2, which predated padding/margin in
Codename One

listLongPressBool

Indicates whether a list should handle

long press events, defaults to true

mapTileLoadingImage

An image to preview while loading the

14
MapComponent tile

mapTileLoadingText

The text of the tiles in the

15
MapComponent during loading,
defaults to "Loading"

mapZoomButtonsBool

Indicates whether buttons should be

drawn on the map component

mediaBackImage

Media icon used by the media player

class

mediaFwdImage

Media icon used by the media player

class

mediaPauseImage

Media icon used by the media player

class

mediaPlayImage

Media icon used by the media player

class

menuButtonBottomBool

When set to true this flag aligns the

menu button to the bottom portion of the
title. Defaults to false

14
15

https://www.codenameone.com/javadoc/com/codename1/maps/MapComponent.html
https://www.codenameone.com/javadoc/com/codename1/maps/MapComponent.html

140

Advanced Theming
Constant

Description/Argument

menuButtonTopBool

When set to true this flag aligns the

menu button to the top portion of the
title. Defaults to false

menuHeightPercent

Allows positioning and sizing the menu

menuImage

The three dot menu image used in

16
Android and the Toolbar to show
additional command entries

menuImageSize

The size in millimeters (floating point

value) of the generated side menu
image, this is only used if you dont
supply a custom image. The default
value is 4.5.

menuPrefSizeBool

Allows positioning and sizing the menu

menuSlideDirection

Defines menu entrance effect

menuSlideInDirBool

Defines menu entrance effect

menuSlideOutDirBool

Defines menu entrance effect

menuTransitionIn

Defines menu entrance effect

menuTransitionInImage

Defines menu entrance effect

menuTransitionOut

Defines menu exit effect

menuTransitionOutImage

Defines menu entrance effect

menuWidthPercent

Allows positioning and sizing the menu

minimizeOnBackBool

Indicates whether the form should

minimize the entire application when
the physical back button is pressed (if
available) and no command is defined as
the back command. Defaults to true

onOffIOSModeBool

Indicates whether the on/off switch

should use the iOS or Android mode

otherPopupRendererBool

Indicates that a separate renderer UIID/

instance should be used to the list within
the combo box popup

16

https://www.codenameone.com/javadoc/com/codename1/ui/Toolbar.html

141

Advanced Theming
Constant

Description/Argument

PackTouchMenuBool

Enables preferred sized packing of the

touch menu (true by default), when set
to false this allows manually determining
the touch menu size using percentages

paintsTitleBarBool

Indicates that the StatusBar UIID should

be added to the top of the form to space
down the title area, as is the case on iOS
7+ where the status bar is painted on top
of the UI

popupCancelBodyBool

Indicates that a cancel button should

appear within the combo box popup

PopupDialogArrowBool

Indicates whether the popup dialog has

an arrow, notice that this constant will
change if you change UIID of the popup
dialog

PopupDialogArrowBottomImage

Image of the popup dialog arrow, notice

that this constant will change if you
change UIID of the popup dialog

PopupDialogArrowTopImage

Image of the popup dialog arrow, notice

that this constant will change if you
change UIID of the popup dialog

PopupDialogArrowLeftImage

Image of the popup dialog arrow, notice

that this constant will change if you
change UIID of the popup dialog

PopupDialogArrowRightImage

Image of the popup dialog arrow, notice

that this constant will change if you
change UIID of the popup dialog

popupNoTitleAddPaddingInt

Adds padding to a popup when no title is

present

popupTitleBool

Indicates that a title should appear within

the combo box popup

pullToRefreshImage

The arrow image used to draw the

pullToRefresh animation

pureTouchBool

Indicates the pure touch mode

142

Advanced Theming
Constant

Description/Argument

radioOppositeSideBool

Indicates the radio button should be

drawn on the opposite side to the text
and not next to the text

radioSelectedDisImage

Radio button image

radioSelectedImage

Radio button image

radioUnselectedDisImage

Radio button image

radioUnselectedImage

Radio button image

releaseRadiusInt

Indicates the distance from the button

with dragging, in which the button should
be released, defaults to 0

rendererShowsNumbersBool

Indicates whether renderers should

render the entry number

reverseSoftButtonsBool

Swaps the softbutton positions

rightSideMenuImage

Same as sideMenuImage only for the

right side, optional and defaults to
sideMenuImage

rightSideMenuPressImage

Same as sideMenuPressImage only for

the right side, optional and defaults to
sideMenuPressImage

showBackCommandOnTitleBool

Used by the Toolbar API to indicate

whether the back button should appear
on the title

shrinkPopupTitleBool

Indicates the title of the popup should be

set to 0 if its missing

sideMenuAnimSpeedInt

The speed at which a sidemenu moves

defaults to 300 milliseconds

sideMenuFoldedSwipeBool

Indicates the side menu could be

opened via swiping

sideMenuImage

The image representing the side menu,

three lines (Hamburger menu)

sideMenuPressImage

Optional pressed version of the

sideMenuImage

17

17

https://www.codenameone.com/javadoc/com/codename1/ui/Toolbar.html

143

Advanced Theming
Constant

Description/Argument

sideMenuShadowBool

Indicates whether the shadow for the

side menu should be drawn

sideMenuShadowImage

The image used when drawing the

shadow (a default is used if this isnt
supplied)

sideMenuSizeTabPortraitInt

The size of the side menu when

expanded in a tablet in portrait mode

sideMenuSizePortraitInt

The size of the side menu when

expanded in a phone in portrait mode

sideMenuSizeTabLandscapeInt

The size of the side menu when

expanded in a tablet in landscape mode

sideMenuSizeLandscapeInt

The size of the side menu when

expanded in a phone in landscape mode

sideMenuTensileDragBool

Enables/disables the tensile drag

behavior within the opened side menu

sideSwipeActivationInt

Indicates the threshold in the side menu

bar at which a swipe should trigger
activation, defaults to 15 (percent)

sideSwipeSensitiveInt

Indicates the region of the screen that is

sensitive to side swipe in the side menu
bar, defaults to 10 (percent)

slideDirection

Default slide transition settings

slideInDirBool

Default slide transition settings

slideOutDirBool

Default slide transition settings

sliderThumbImage

The thumb image that can appear on the

sliders

snapGridBool

Snap to grid toggle

statusBarScrollsUpBool

Indicates that a tap on the status bar

should scroll up the UI, only relevant in
OSs where paintsTitleBarBool is true

switchButtonPadInt

Indicates the padding in the on/off

switch, defaults to 16

144

Advanced Theming
Constant

Description/Argument

switchMaskImage

Indicates the mask image used in iOS

mode to draw on top of the switch

switchOnImage

Indicates the on image used in iOS

mode to draw the on/off switch

switchOffImage

Indicates the off image used in iOS

mode to draw the on/off switch

TabEnableAutoImageBool

Indicates images should be filled by

default for tabs

TabSelectedImage

Default selected image for tabs (if

TabEnableAutoImageBool=true)

TabUnselectedImage

Default unselected image for tabs (if

TabEnableAutoImageBool=true)

tabPlacementInt

The placement of the tabs in the

18
Tabs component: TOP = 0, LEFT = 1,
BOTTOM = 2, RIGHT = 3

tabsSlideSpeedInt

The time of the animation that occurs

(in milliseconds) between between
releasing a swiped tab and reaching the
next tab. Currently defaults to 200

tabsFillRowsBool

Indicates if the tabs should fill the row

using flow layout

tabsGridBool

Indicates whether tabs should use a

grid layout thus forcing all tabs to have
identical sizes

tabsOnTopBool

Indicates the tabs should be drawn on

top of their content in a layered UI, this
allows a tab to intrude into the content of
the tabs

textCmpVAlignInt

18

The vertical alignment of the text

component: TOP = 0, CENTER = 4,
BOTTOM = 2

https://www.codenameone.com/javadoc/com/codename1/ui/Tabs.html

145

Advanced Theming
Constant

Description/Argument

textFieldCursorColorInt

The color of the cursor as an integer (not

hex)

tickerSpeedInt

The speed of label/button etc. (in

milliseconds)

tintColor

The aarrggbb hex color to tint the screen

when a dialog is shown

topMenuSizeTabPortraitInt

The size of the side menu when

expanded and attached to the top in a
tablet in portrait mode

topMenuSizePortraitInt

The size of the side menu when

expanded and attached to the top in a
phone in portrait mode

topMenuSizeTabLandscapeInt

The size of the side menu when

expanded and attached to the top in a
tablet in landscape mode

topMenuSizeLandscapeInt

The size of the side menu when

expanded and attached to the top in a
phone in landscape mode

touchCommandFillBool

Indicates how the touch menu should

layout the commands within

touchCommandFlowBool

Indicates how the touch menu should

layout the commands within

transitionSpeedInt

Indicates the default speed for

transitions

treeFolderImage

Picture of a folder for the Tree

treeFolderOpenImage

Picture of a folder expanded for the

Tree class

treeNodeImage

Picture of a file node for the Tree class

tensileDragBool

Indicates that tensile drag should be

enabled/disabled. This is usually set by
platform themes

19

https://www.codenameone.com/javadoc/com/codename1/ui/tree/Tree.html

146

19

class

Advanced Theming

Dynamic Theme Swapping & Theme Constants

Once a theme constant is set by a theme, it isnt removed on a refresh when
replacing the theme.
E.g. if one would set the comboImage constant to a specific value in theme A
and then switch to theme B, that doesnt define the comboImage , the original
theme A comboImage might remain!
The reason for this is simple: when extracting the constant values, components
keep the values in cache locally and just dont track the change in
value. Furthermore, since the components allow manually setting values, its
impractical for them to track whether a value was set by a constant or explicitly
by the user.
The solution for this is to either manually reset undesired values before replacing
a theme (e.g. for the case, above by calling the default look and feel method
for setting the combo image with a null value), or defining a constant value to
replace the existing value.

4.5.Native Theming
Codename One uses a theme constant called includeNativeBool , when that
constant is set to true Codename One starts by loading the native theme first and
then applying all the theme settings. This effectively means your theme "derives" the
style of the native theme first, similar to the cascading effect of CSS. Internally this is
exactly what the theme layering section covered.
By avoiding this flag you can create themes that look EXACTLY the same on all
platforms.
If you avoid the native theming you you might be on your own. A few
small device oddities such as the iOS status bar are abstracted by
native theming. Without it you will need to do everything from scratch.
You can simulate different OS platforms by using the native theme menu option

147

Advanced Theming

Figure 4.3. The native theme menu option

Developers can pick the platform of their liking and see how the theme will appear in
that particular platform by selecting it and having the preview update on the fly.

4.6.How Does A theme Work?

To truly understand a theme we need to understand what it is. Internally a theme is just
a Hashtable key/value pair between UIID based keys and their respective values.
E.g. the key:
Button.fgColor=ffffff

Will set the foreground color of the Button

20

UIID to white.

21

22

When a Codename One Component is instantiated it requests a Style object from

23
the UIManager class. The Style object is based on the settings within the theme
and can be modified thru code or by using the theme.
We can replace the theme dynamically in runtime and refresh the styles assigned to
24
the various components using the refreshTheme() method.
Its a common mistake to invoke refreshTheme() without
actually changing the theme. We see developers doing it when
all they need is a repaint() or revalidate() . Since
20

https://www.codenameone.com/javadoc/com/codename1/ui/Button.html
21
https://www.codenameone.com/javadoc/com/codename1/ui/Component.html
22
https://www.codenameone.com/javadoc/com/codename1/ui/plaf/Style.html
23
https://www.codenameone.com/javadoc/com/codename1/ui/plaf/UIManager.html
24
https://www.codenameone.com/javadoc/com/codename1/ui/Component.html#refreshTheme--

148

Advanced Theming
refreshTheme() is very expensive we recommend that you dont
use it unless you really need to
A theme Hashtable key is comprised of:
[UIID.][type#]attribute
The UIID, corresponds to the components UIID e.g. Button , CheckBox

25

etc. It is

optional and may be omitted to address the global default style.

The type is omitted for the default unselected type, and may be one of sel (selected
type), dis (disabled type) or press (pressed type). The attribute should be one of:
derive - the value for this attribute should be a string representing the base
component.
bgColor - represents the background color for the component, if applicable, in a
web hex string format RRGGBB e.g. ff0000 for red.
fgColor - represents the foreground color, if applicable.
border - an instance of the border class, used to display the border for the
component.
bgImage - an Image

26

object used in the background of a component.

transparency - a String containing a number between 0-255 representing the

alpha value for the background. This only applies to the bgColor.
margin - the margin of the component as a String containing 4 comma
separated numbers for top,bottom,left,right.
padding - the padding of the component, it has an identical format to the margin
attribute.
font - A Font

27

object instance.

alignment - an Integer object containing the LEFT/RIGHT/CENTER constant

values defined in Component.
textDecoration
- an
Integer
value containing
TEXT_DECORATION_* constant values defined in Style.

one

of

the

backgroundType - a Byte object containing one of the constants for the

28
background type defined in Style under BACKGROUND_*.
25
https://www.codenameone.com/javadoc/com/codename1/ui/CheckBox.html
26
https://www.codenameone.com/javadoc/com/codename1/ui/Image.html
27
https://www.codenameone.com/javadoc/com/codename1/ui/Font.html
28
https://www.codenameone.com/javadoc/com/codename1/ui/plaf/Style.html

149

Advanced Theming
backgroundGradient - contains an Object array containing 2 integers for the
colors of the gradient. If the gradient is radial it contains 3 floating points defining
the x, y & size of the gradient.
So to set the foreground color of a selected button to red, a theme will define a property
like:
Button.sel#fgColor=ff0000
This information is mostly useful for understanding how things work within Codename
One, but it can also be useful in runtime.
E.g. to increase the size of all fonts in the application, we can do something like:
Hashtable h = new Hashtable();
h.put("font", largeFont);

UIManager.getInstance().addThemeProps(h);
Display.getInstance().getCurrent().refreshTheme();

4.7.Understanding Images & Multi-Images

This section provides a very high level overview of images. We dive
deeper into the various types of images in the graphics section.
When working with a theme, we often use images for borders or backgrounds. We also
use images within the GUI for various purposes and most such images will be extracted
from the resource file.
Adding a standard JPEG/PNG image to the resource file is straight forward, and the
resulting image can be viewed within the images section. However, due to the wide
difference between device types, an image that would be appropriate in size for an
iPhone 3gs would not be appropriate in size for a Nexus device or an iPhone 4 (but
perhaps, surprisingly, it will be just right for iPad 1 & iPad 2).

Device Density: DPI/PPI

DPI (Dots Per Inch) & PPI (Pixels Per Inch) are two shorthand terms used to
discuss the variety of device densities. Densities are confusing for first time
Codename One developers who struggle with the notion that an iPad might get
the same resolution image as a phone.
150

Advanced Theming
A first generation the iPad 2 device had a 160 PPI (160 pixels per inch density).
The much smaller iPhone 4 from the same era had 320 PPI and modern devices
already exceed 600+ PPI values. The contrast is staggering especially when
compared to the desktop.
Mobile UIs are expected to use all available pixels to their full extent. In that
sense when an application runs on a tablet you dont want it to just provide a
larger image for the icons but rather have it cram more information into a single
form. So we need to rethink image sizing not just in pixels but in millimeters/
inches.
The density of the devices varies significantly and Codename One tries to simplify the
process by unifying everything into one set of values to indicate density. For simplicitys
sake, density is sometimes expressed in terms of pixels, however it is mapped internally
to actual screen measurements where possible.
A multi-image is an image that has multiple varieties for different densities, and thus
looks sharp in all the densities. Since scaling on the device cant interpolate the
data (due to performance considerations), significant scaling on the device becomes
impractical. However, a multi-image will just provide the right resolution image for the
given device type.
From the programming perspective this is mostly seamless, a developer just accesses
one image and has no ability to access the images in the different resolutions. Within the
designer, however, we can explicitly define images for multiple resolutions and perform
high quality scaling so the right image is available.
We can use two basic methods to add a multi-image: quick add & standard add.
Both methods rely on understanding the source resolution of the image, e.g. if you have
an icon that you expect to be 128x128 pixels on iPhone 4, 102x102 on nexus one and
64x64 on iPhone 3gs. You can provide the source image as the 128 pixel image and
just perform a quick add option while picking the Very High density option.
This will indicate to the algorithm that your source image is designed for the "very high"
density and it will scale for the rest of the densities accordingly.
This relies on the common use case of asking your designer to
design for one high end device (e.g. iPhone 6+) then you can just
take the resources and add them as "HD" resources and they will
automatically adapt to the lower resolutions.
151

Advanced Theming
Alternatively, you can use the standard add multi-image dialog and set it like this:

Notice that we selected the square image option, essentially eliminating the height
option. Setting values to 0 prevents the system from generating a multi-image entry
for that resolution, which will mean a device in that category will fall on the closest
alternative.
The percentage value will change the entire column, and it means the percentage of
the screen. E.g. We know the icon is 128 for the very high resolution, we can just move
the percentage until we reach something close to 128 in the Very High row and the
other rows will represent a size that should be pretty close in terms of physical size
to the 128 figure.
At runtime, you can always find the host devices approximate pixel density using the
Display.getDeviceDensity() method. This will return one of:

Table 4.2. Densities

Constant

Density

Example Device

Display.DENSITY_VERY_LOW
~ 88 ppi
152

Advanced Theming
Display.DENSITY_LOW ~ 120 ppi

Android ldpi devices

Display.DENSITY_MEDIUM
~ 160 ppi

iPhone 3GS, iPad,

Android mdpi devices

Display.DENSITY_HIGH ~ 240 ppi

Android hdpi devices

Display.DENSITY_VERY_HIGH
~ 320 ppi

iPhone 4, iPad Air 2,

Android xhdpi devices

Display.DENSITY_HD

iPhone 6+, Android xxhdpi

devices

~ 540 ppi

Display.DENSITY_560 ~ 750 ppi

Android xxxhdpi devices

Density.DENSITY_2HD ~ 1000 ppi

Density.DENSITY_4K

~ 1250ppi

4.8.Use Millimeters for Padding/Margin & Font

Sizes
When configuring your styles, you should almost never use "Pixels" as the unit
for padding, margins, font size, and border thickness because the results will be
inconsistent on different densities. Instead, you should use millimeters for all non-zero
units of measurement.
As we now understand the complexities of DPI it should be clear why this is important.

4.8.1.Fractions of Millimeters
Sometimes millimeters dont give you enough precision for what you want to do.
Currently the designer only allows you to specify integer values for most units.
However, you can achieve more precise results when working directly in Java. The
Display.convertToPixels() method will allow you to convert millimeters (or
DIPS) to pixels. It also only takes an integer input, but you can use it to obtain a multiplier
that you can then use to convert any millimeter value you want into pixels.
E.g.
double pixelsPerMM = ((double)Display.getInstance().convertToPixels(10,
true)) / 10.0;

And now you can set the padding on an element to 1.5mm. E.g.
153

Advanced Theming

myButton.getAllStyles().setPaddingUnit(Style.UNIT_TYPE_PIXELS);
int pixels = (int)(1.5 * pixelsPerMM);

myButton.getAllStyles().setPadding(pixels, pixels, pixels, pixels);

4.9.Converting a PSD To A Theme

Codename One provides extensive support for designing beautiful user interfaces, but
it isnt necessarily obvious to new developers how to achieve their desired results. A
common workflow for app design includes a PSD file with mock-ups of the UI, created
by a professional designer.
PSD is the Adobe Photoshop file format, its the most common format
for UI designs in the industry
For this tutorial we adapt a very slick looking sign-up form found online and convert it
to a Codename One component that can be used inside an application.
The process we followed was:
1. Find the PSD design we want to use: this PSD file
31
(we mirrored it here in case it goes offline):

29
30
31

http://freebiesbug.com/psd-freebies/iphone-6-ui-kit/
https://dribbble.com/adrianchiran
https://www.codenameone.com/files/iOS_UI-Kit.psd

154

29

created by Adrian Chiran

30

Advanced Theming

155

Advanced Theming
2. Re-create the general structure and layout of the design in a Codename One Form
using nested components and layout managers. Here is a break-down of how we
structured the component hierarchy in the Form :

Figure 4.5. Component hierarchy and layouts

3. Extract the images we needed using Photoshop - this process is often referred to
as "cutting"
4. Extract the fonts, colors, and styles we needed to reproduce the design in
Codename One
5. Import images into the Codename one project, and define theme styles so that our
components match the look of the original design
Here is a screenshot of the resulting component running inside the Codename One
simulator:

156

Advanced Theming

Figure 4.6. Resulting app in the Codename One simulator

157

Advanced Theming

4.9.1.Breaking Down the PSD

Open the PSD you are interested in using Photoshop.
You might be missing fonts in your system so you can either install
them or ignore that. Keep in mind that some fonts might not be
redistributable with your application
In this PSD we want only one of the screen designs so initially we want to remove
everything that isnt related so we can get our bearings more effectively:
Select the drag tool (the top left tool)
In the toolbar for the tool (top bar area) check the Auto Select mode
Select the Layer Mode for auto selection (in some cases group would actually be
better so feel free to experiment)
Click on the portion in the PSD that you are interested in
You should end up with something like this where a layer is selected in the layers
window:

Figure 4.7. Selecting a layer from the region you are interested in
Scroll up the hierarchy a bit and uncheck/recheck the eye icon on the left until you
locate the right element layer.
158

Advanced Theming

Figure 4.8. Selecting a layer from the region you are interested in
Right click the layer and select Convert To Smart Object.
The right click menu will present different options when you click
different areas of the layer, clicking on the left area of the layer works

159

Advanced Theming

Figure 4.9. In the right click menu option select "Convert To Smart
Object"
Once the layer hierarchy is a smart object you can just double click it which will open
the sub hierarchy in a new tab and you now only have the pieces of the image you
care about.

160

Advanced Theming

Figure 4.10. Double clicking the smart object allows us to edit only
the form we need

Removing the Noise

The first thing we need to do is remove from the image all of the things that we dont
really need. The status bar area on the top is redundant as if is a part of the phones UI.
We can select it using the select tool and click the eye icon next to the layer to hide it.
Normally wed want to have the back arrow but thanks to the material design icons that
are a part of Codename One we dont need that icon so we can hide that too.
We dont need the "Sign Up" or "Done" strings in the title either but before removing
them wed like to know the font that is used.
To discover that I can click them to select the layer then switch to the text tool:

161

Advanced Theming

Figure 4.11. The text tool allows us to inspect the font used
Then I can double click the text area layer to find out the font in the top of the UI like this:

Figure 4.12. The Done toolbar entry uses SourceSansPro Regular

Notice that I dont actually need to have the font installed in this case
I dont (hence the square brackets)

162

Advanced Theming
Also notice that the color of the font is accessible in that toolbar, by clicking the color
element we get this dialog which shows the color value to be f73267, this is something
we will use later

Figure 4.13. The color dialog lists the hex color at the bottom, we
can paste that directly to the designer tool
We can now hide both text layers so they wont pose a problem later.

The Camera Button

The camera button includes an icon and the button background itself. You can just use
that as a single image and be done with it, but for the purpose of this tutorial I will take
the harder route of separating this into a button background and a foreground image.
When you click on the camera icon you will notice that the camera icon is comprised
of two separate layers: the camera and the "x" symbol above it. We can select both
layers using ctrl-click (command click on the Mac) and convert both to a smart object
together using the same method as before:

163

Advanced Theming

Figure 4.14. The camera smart object

Since the image is used as an icon we want it to be completely square which isnt the
situation here!
This is important as a non-square image can trigger misalignment when dealing with
icons and the background. So we need to use the Image Canvas Size menu and
set the values to be the same (the higher value of the two).

Figure 4.15. The canvas size dialog for the camera.png file

164

Advanced Theming
We can now use File Save As and save the first image resource we will need into a
temporary directory. Make sure to save a PNG file to preserve quality and transparency!
For convenience well refer to the file as camera.png when we need it later.

Figure 4.16. The camera icon image

We can follow the exact same procedure with the parent button layer (the white portion)
which we can convert to a smart object and save as camera-button.png .

Figure 4.17. The camera button image set to a gray

background so it will be visible
Now we can hide both of these elements and proceed to get the background image
for the title.
Here the "smart object trick" wont work There is an effects layer in place and the
smart object will provide us with the real underlying image instead of the look we actually
want. However, solving this is trivial now that we hid all of the elements on top of the
image!
We need to switch to the rectangular select tool:

165

Advanced Theming

Figure 4.18. The select tool and the clean image we want to select
Now drag the select tool to select the image dont cross into the white pixels below the
image. You can use the zoom value and set it to a very high value to get the selection
right.
When the selection is right click Edit Copy Merged. Normally Copy would only copy
a specific layer but in this case we want to copy what we see on the screen!
Now click File New it should have the Presets set to Clipboard which means the
newly created image is based on what we just copied (that is seriously great UX). Just
accept that dialog and paste (Ctrl-V or Command-V).
You can now save the image, since its just a background using JPEG is totally
acceptable in this case. We named it background.jpg .

166

Advanced Theming

Figure 4.19. The background image

The last thing we need is the colors used in the UI. We can use the "eye drop" tool
in a high zoom level to discover the colors of various elements e.g. the text color is
4d606f and the separator color is f5f5f5 :

Figure 4.20. The eye drop tool can be pointed at an area of the image
to get the color in that region

167

Advanced Theming

4.9.2.The Code
While that was verbose it was relatively simple. Well create a simple barebones manual
application with the native theme.
The reason for this is to avoid "noise", if we use a more elaborate
theme it would have some existing settings. This can make the
tutorial harder to follow

Figure 4.21. Simple bare bones app settings

Once the project is created double click the theme.res file and within the designer

select Images Quick Add Multi Images. Select the 3 images we created above:
background.jpg , camera.png & camera-button.png . Leave the default
setting on Very High and press OK.
Then save the resource file so we can use these images from code.
Here is the source code we used to work with the UI above there are comments within
the code explaining some of the logic:
private Label createSeparator() {
Label sep = new Label();

sep.setUIID("Separator");

168

Advanced Theming
// the separator line

is implemented in the theme using padding and

background color, by default labels

// are hidden when they have no content, this method disables that

behavior

sep.setShowEvenIfBlank(true);

return sep;

public void start() {

if(current != null){
current.show();

return;

// The toolbar uses the layered mode so it resides on top of the

background image, the theme makes

// it transparent so we will see the image below it, we use border

layout to place the background image on

// top and the "Get started" button in the south

Form psdTutorial = new Form("Signup", new BorderLayout());

Toolbar tb = new Toolbar(true);
psdTutorial.setToolbar(tb);

// we create 4mm material arrow images for the back button and the Get

started button

Style iconStyle =
psdTutorial.getUIManager().getComponentStyle("Title");
FontImage leftArrow =
FontImage.createMaterial(FontImage.MATERIAL_ARROW_BACK, iconStyle, 4);
FontImage rightArrow =
FontImage.createMaterial(FontImage.MATERIAL_ARROW_FORWARD, iconStyle, 4);
// we place the back and done commands in the toolbar, we need to

change UIID of the "Done" command

// so we can color it in Red

tb.addCommandToLeftBar("", leftArrow, (e) -> Log.p("Back pressed"));

Command doneCommand = tb.addCommandToRightBar("Done", null, (e) ->
Log.p("Done pressed"));
tb.findCommandComponent(doneCommand).setUIID("RedCommand");
// The camera button is comprised of 3 pieces. A label containing the

image and the transparent button

// with the camera icon on top. This is all wrapped in the title

container where the title background image

// is placed using the theme. We chose to use a Label rather than a

background using the cameraLayer so

169

Advanced Theming
// the label will preserve the original size of the image without

scaling it and take up the space it needs

Button cameraButton = new Button(theme.getImage("camera.png"));

Container cameraLayer = LayeredLayout.encloseIn(

new Label(theme.getImage("camera-button.png")),

cameraButton);
cameraButton.setUIID("CameraButton");
Container titleContainer = Container.encloseIn(

new BorderLayout(BorderLayout.CENTER_BEHAVIOR_CENTER),

cameraLayer, BorderLayout.CENTER);
titleContainer.setUIID("TitleContainer");

TextField firstName = new TextField("", "First Name");

TextField lastName = new TextField("", "Last Name");

TextField email = new TextField("", "Email Address", 20,

TextField.EMAILADDR);

TextField password = new TextField("", "Choose a Password", 20,

TextField.PASSWORD);

TextField phone = new TextField("", "Phone Number", 20,

TextField.PHONENUMBER);

Label phonePrefix = new Label("+1");

phonePrefix.setUIID("TextField");

// The phone and full name have vertical separators, we use two table

layouts to arrange them correctly

// so the vertical separator will be in the right place

TableLayout fullNameLayout = new TableLayout(1, 3);
Container fullName = new Container(fullNameLayout);

fullName.add(fullNameLayout.createConstraint().widthPercentage(49),
firstName).
add(fullNameLayout.createConstraint().widthPercentage(1),
createSeparator()).
add(fullNameLayout.createConstraint().widthPercentage(50),
lastName);
Container fullPhone = TableLayout.encloseIn(3, phonePrefix,
createSeparator(), phone);
// The button in the south portion needs the arrow icon to be on the

right side so we place the text on the left

Button southButton = new Button("Get started", rightArrow);

southButton.setTextPosition(Component.LEFT);
southButton.setUIID("SouthButton");

// we add the components and the separators the center portion

contains all of the elements in a box

170

Advanced Theming
// Y container which we allow to scroll. BorderLayout Containers

implicitly disable scrolling

Container by = BoxLayout.encloseY(
fullName,
createSeparator(),
email,
createSeparator(),
password,
createSeparator(),
fullPhone,
createSeparator()

);
by.setScrollableY(true);
psdTutorial.add(BorderLayout.NORTH, titleContainer).
add(BorderLayout.SOUTH, southButton).
add(BorderLayout.CENTER, by);

psdTutorial.show();

4.9.3.Styling The UI
So the code above is most of the work but we still need to put everything together using
the theme. This is what we have so far:

171

Advanced Theming

Figure 4.22. Before applying the changes to the theme this is what
we have

172

Advanced Theming

Figure 4.23. This is what we are aiming at with no additional code

changes
This looks like a major set of changes but it requires exactly 10 UIID definitions to get
to this look!
Open the designer and select the theme. Press the Add button and type in
TitleContainer. Uncheck derive for the background and select IMAGE_SCALED_FILL
for the Type and the background.jpg image.
Define the padding as:
Left - 3 millimeter
173

Advanced Theming
Right - 3 millimeter
Top - 8 millimeter
Bottom - 2 millimeter
This will allow enough space for the title. Define margin as 0 on all sides. Then press
OK.
Add the "Title" UIID. In the Color tab define the foreground as ffffff define
transparency as 0 (fully transparent so we will see the TitleContainer ). Define
padding as 1 millimeter on all sides and margin as 0 on all sides.
In the Border tab press the button and select [Empty].
In the Font tab select the True Type as native:MainThin. Select the True Type Size as
millimeters and set the value to 3.5 .
Press OK to save the changes.
Copy the Title UIID and paste it, change the name to "TitleCommand" and press
OK to save the changes.
Copy the Title UIID again and paste it, change the name to "RedCommand". In the
Color tab set the foreground color to f73267 . In the Font tab set the True Type to
native:MainLight and set the size to 3. Press OK to save the changes.
Add the "TitleArea" UIID. In the Color tab define transparency as 0 (fully transparent
so we will see the TitleContainer ). Define padding and margin as 0 on all sides.
In the Border tab press the button and select [Empty]. Press OK to save the changes.
Add the "TextField" UIID. In the Color tab define transparency as 255 (fully opaque)

and the background as ffffff (white). Define padding as 2 millimeter on all sides
and margin as 0 on all sides.
In the Border tab press the button and select [Empty]. In the Font tab set the True
Type to native:MainLight and set the size to 2. Press OK to save the changes.
Copy the TextField UIID again and paste it, change the name to "TextHint". In the
Color tab set the foreground color to 4d606f . Press OK to save the changes.
Add the "SouthButton" UIID. In the Color tab define transparency as 255 (fully opaque)
and the background as f73267 (red) and the foreground as ffffff (white). Define
Alignment as Center.
174

Advanced Theming

Define padding as:

Left - 1 millimeter
right - 1 millimeter
top - 2 millimeters
bottom - 2 millimeters
Define margin as 0 on all sides. In the Font tab set the True Type to native:MainThin
and set the size to 3. Press OK to save the changes.
Add the "CameraButton" UIID. In the Color tab define transparency as 0 (fully
transparent). Define Alignment as Center.
Define padding as:
Left - 1 millimeter
right - 1 millimeter
top - 3 millimeters
bottom - 1 millimeter
This helps spacing away from the title

Define margin as 1 millimeter on all sides. Press OK to save the changes.

You can now save the theme and the app should look like the final result!

Not Quite There Yet

There is one last piece that you would notice if you actually try to run this code. When
pressing the buttons/text fields you would see their look change completely due to the
different styles for focus/press behavior.
You can derive the regular styles from the selected/pressed styles but one of the
simplest ways is to just copy & paste the styles to the pressed/selected tabs. We
can copy CameraButton , RedCommand , SouthButton & TextField to the
selected state. Then copy CameraButton , RedCommand & SouthButton to the
pressed state to get the complete app running!

175

Chapter5.The Components Of
Codename One
This chapter covers the components of Codename One. Not all components are
1
covered, but it tries to go deeper than the JavaDocs .

5.1.Container
The Codename One container is a base class for many high level components; a
container is a component that can contain other components.
Every component has a parent container that can be null if it isnt within a container at
the moment or is a top-level container. A container can have many children.

Figure 5.1. Component-Container relationship expressed as UML

Components are arranged in containers using layout managers which are algorithms
that determine the arrangement of components within the container.
You can read more about layout managers in the basics section.

5.1.1.Composite Components
Codename One components share a very generic hierarchy of inheritance e.g. Button
3
derives from Label and thus receives all its abilities.
1
2
3

https://www.codenameone.com/javadoc/
https://www.codenameone.com/javadoc/com/codename1/ui/Button.html
https://www.codenameone.com/javadoc/com/codename1/ui/Label.html

176

The Components Of Codename One

4

However, some components are composites and derive from the Container class.
5
E.g. the MultiButton is a composite button that derives from Container but acts/
looks like a Button . Normally this is pretty seamless for the developer, with a few
things to keep in mind.

You should not use the Container derived methods on such a composite
component (e.g. add / remove etc.).
You cant cast it to the type that it relates to e.g. you cant cast MultiButton to
Button .
6

Events might be more nuanced. E.g. if you rely on ActionEvent.getSource()

7
or ActionEvent.getComponent() notice that they might not behave the way you
would expect. For a MultiButton they will return the underlying Button . To
8
workaround this we have ActionEvent.getActualComponent() .

Lead Component
Codename One has a rather unique feature for creating composite
components: "lead components". This feature effectively allows components
like MultiButton to act as if they are a single component while really being
comprised of multiple components.
Lead components work by setting a single component within as the "leader" it
determines the style state for all the components in the hierarchy so if we have a
Container that is lead by a Button the button will determine if the selected/
pressed state is returned for the entire container hierarchy.
This creates a case where a single Component has multiple nested UIIDs
e.g. `MultiButton has UIIDs such as `MultiLine1 that can be
9
customized via APIs such as setUIIDLine1 .
4
5

https://www.codenameone.com/javadoc/com/codename1/ui/Container.html
https://www.codenameone.com/javadoc/com/codename1/components/MultiButton.html

6
https://www.codenameone.com/javadoc/com/codename1/ui/events/ActionEvent.html#getSource-7
https://www.codenameone.com/javadoc/com/codename1/ui/events/ActionEvent.html#getComponent-8
https://www.codenameone.com/javadoc/com/codename1/ui/events/
ActionEvent.html#getActualComponent-9
https://www.codenameone.com/javadoc/com/codename1/components/MultiButton.html#setUIIDLine1java.lang.String-

177

The Components Of Codename One

The lead component also handles the events from a single source so clicking
in one of the other components within the hierarchy will send the event to the
leading Button resulting in action events that behave "oddly" (hence the need
for getActualComponent );
You can learn more about lead components in here.

5.2.Form
10

Form is the top-level container of Codename One, Form derives from Container
and is the element we show. Only one form can be visible at any given time. We can
get the currently visible Form using the code:
Form currentForm = Display.getInstance().getCurrent();

A form is a unique container in the sense that it has a title, a content area and optionally
a menu/menu bar area. When invoking methods such as add / remove on a form,
you are in fact invoking something that maps to this:
myForm.getContentPane().add(...);
11

Form is in effect just a Container that has a border layout, its north section is
occupied by the title area and its south section by the optional menu bar. The center
(which stretches) is the content pane. The content pane is where you place all your
components.

10
11

https://www.codenameone.com/javadoc/com/codename1/ui/Form.html
https://www.codenameone.com/javadoc/com/codename1/ui/Container.html

178

The Components Of Codename One

Figure 5.2. Form layout graphic

You can see that every Form has space allocated for the title area. If you dont set the
title it wont show up (its size will be zero), but it will still be there. The same isnt always
true for the case of the menu bar, which can vary significantly. Effectively, the section
that matters is the content pane, so the form tries to do the right thing by pretending to
be the content pane. However, this isnt always seamless and sometimes code needs
to just invoke getContentPane() in order to work directly with the container.
A good example for such a case is with layout animations. Animating
the form might not produce the right results. When in doubt its pretty
easy to just use getContentPane instead of working with the
Form directly.
As you can see from the graphic, Form has two layers that reside on top of
the content pane/title. The first is the layered pane which allows you to place
"always on top" components. The layered pane added implicitly when you invoke
getLayeredPane() .
You still need to place components using layout managers in order
to get them to appear in the right place when using the layered pane.

179

The Components Of Codename One

The second layer is the glass pane which allows you to draw arbitrary things on top of
everything. The order in the image is indeed accurate:
1. ContentPane is lowest
2. LayeredPane is second
3. GlassPane is painted last
Its important to notice that a layered pane is on top of the
ContentPane only and doesnt stretch to the title. A GlassPane
usually stretches all the way but only with a "lightweight" title area
12
e.g. the Toolbar API .
The GlassPane allows developers to overlay UI on top of existing UI and paint as
they see fit. This is useful for things that provide notification but dont want to intrude
with application functionality.
Both LayeredPane & GlassPane wont work with "native" peer
components such as media, browser, native maps etc.

5.3.Dialog
13

A Dialog is a special kind of Form that can occupy only a portion of the screen, it
also has the additional functionality of the modal show method.
When showing a dialog we have two basic options: modeless and modal:
Modal dialogs (the default) block the current EDT thread until the dialog is dismissed
(to understand how they do it, read about invokeAndBlock ).
Modal dialogs are an extremely useful way to prompt the user since the code can
assume the user responded in the next line of execution. This promotes a linear &
intuitive way of writing code.

Modless dialogs return immediately so a call to show such a dialog cant assume
anything in the next line of execution. This is useful for features such as progress
indicators where we arent waiting for user input.
E.g. a modal dialog can be expressed as such:
12
13

https://www.codenameone.com/javadoc/com/codename1/ui/Toolbar.html
https://www.codenameone.com/javadoc/com/codename1/ui/Dialog.html

180

The Components Of Codename One

if(Dialog.show("Click Yes Or No", "Select one", "Yes", "No")) {

// user clicked yes

} else {
}

// user clicked no

Notice that during the show call above the execution of the next line was "paused"
until we got a response from the user and once the response was returned we could
proceed directly.
All usage of Dialog must be within the Event Dispatch Thread (the
default thread of Codename One). This is especially true for modal
dialogs. The Dialog class knows how to "block the EDT" without
blocking it.
To learn more about invokeAndBlock which is the workhorse behind the modal
dialog functionality check out the EDT section.
The Dialog class contains multiple static helper methods to quickly show user
notifications, but also allows a developer to create a Dialog instance, add information
to its content pane and show the dialog.
Dialogs contain a ContentPane just like Form .

When showing a dialog in this way, you can either ask Codename One to position
14
the dialog in a specific general location (taken from the BorderLayout concept for
locations) or position it by spacing it (in pixels) from the 4 edges of the screen.
E.g. you could do something like this to show a simple modal Dialog :
Dialog d = new Dialog("Title");

d.setLayout(new BorderLayout());

d.add(BorderLayout.CENTER, new SpanLabel("Dialog Body", "DialogBody"));

d.showPacked(BorderLayout.SOUTH, true);

14

https://www.codenameone.com/javadoc/com/codename1/ui/layouts/BorderLayout.html

181

The Components Of Codename One

Figure 5.3. Custom modal Dialog in the south position

You can turn the code above to a modless Dialog by flipping the
boolean true argument to false .
We can position a Dialog absolutely by determining the space from the edges e.g.
with this code we can occupy the bottom portion of the screen:
Dialog d = new Dialog("Title");

d.setLayout(new BorderLayout());

d.add(BorderLayout.CENTER, new SpanLabel("Dialog Body", "DialogBody"));

182

The Components Of Codename One

d.show(hi.getHeight() / 2, 0, 0, 0);

Figure 5.4. Custom Dialog positioned absolutely

hi is the name of the parent Form in the sample above.

183

The Components Of Codename One

5.3.1.Styling Dialogs
Its important to style a Dialog using getDialogStyle()

15

or setDialogUIID

16

methods

rather than styling the dialog object directly.

The reason for this is that the Dialog is really a Form that takes up the whole
screen. The Form that is visible behind the Dialog is rendered as a screenshot. So
customizing the actual UIID of the Dialog wont produce the desired results.

5.3.2.Tint & Blurring

By default a Dialog uses a platform specific tint color when it is showing e.g. notice
the background in the image below is tinted:
Form hi = new Form("Tint Dialog", new BoxLayout(BoxLayout.Y_AXIS));
Button showDialog = new Button("Tint");

showDialog.addActionListener((e) -> Dialog.show("Tint", "Is On....", "OK",

null));
hi.add(showDialog);
hi.show();

15
16

https://www.codenameone.com/javadoc/com/codename1/ui/Dialog.html#getDialogStyle-https://www.codenameone.com/javadoc/com/codename1/ui/Dialog.html#setDialogUIID-

java.lang.String-

184

The Components Of Codename One

Figure 5.5. Dialog with tinted background

The tint color can be manipulated on the parent form, you can set it to any AARRGGBB
value to set any color using the setTintColor method. Notice that this is invoked
on the parent form and not on the Dialog !
This is an AARRGGBB value and not an RRGGBB value! This
means that 0 will be transparent.
You can also manipulate this default value globally using the theme constant
tintColor . The sample below tints the background in green:

185

The Components Of Codename One

Form hi = new Form("Tint Dialog", new BoxLayout(BoxLayout.Y_AXIS));

hi.setTintColor(0x7700ff00);

Button showDialog = new Button("Tint");

showDialog.addActionListener((e) -> Dialog.show("Tint", "Is On....", "OK",

null));
hi.add(showDialog);
hi.show();

Figure 5.6. Dialog with green tinted background

We can apply Gaussian blur to the background of a dialog to highlight
the foreground further and produce a very attractive effect. We can use the
186

The Components Of Codename One

setDefaultBlurBackgroundRadius to apply this globally, we can use the theme
constant dialogBlurRadiusInt to do the same or we can do this on a per Dialog
basis using setBlurBackgroundRadius .

Not
all
device
types
support
blur
you
can
test
if
your
device
supports
it
using
Display.getInstnace().isGaussianBlurSupported() . If
blur isnt supported the blur setting will be ignored.
Form hi = new Form("Blur Dialog", new BoxLayout(BoxLayout.Y_AXIS));
Dialog.setDefaultBlurBackgroundRadius(8);
Button showDialog = new Button("Blur");

showDialog.addActionListener((e) -> Dialog.show("Blur", "Is On....", "OK",

null));
hi.add(showDialog);
hi.show();

187

The Components Of Codename One

Figure 5.7. The blur effect coupled with the OS default tint
It might be a bit hard to notice the blur effect with the tinting so here is the same code
with tinting disabled:
hi.setTintColor(0);

188

The Components Of Codename One

Figure 5.8. The blur effect is more pronounced when the tint is
disabled

5.3.3.Popup Dialog
A popup dialog is a common mobile paradigm showing a Dialog that points at a
specific component. Its just a standard Dialog that is shown in a unique way:
Dialog d = new Dialog("Title");

d.setLayout(new BorderLayout());

d.add(BorderLayout.CENTER, new SpanLabel("Dialog Body", "DialogBody"));

189

The Components Of Codename One

d.showPopupDialog(showDialog);

Figure 5.9. Popup Dialog

The popup dialog accepts a Component
rest.

17
18

17

or Rectangle

18

to point at and handles the

https://www.codenameone.com/javadoc/com/codename1/ui/Component.html
https://www.codenameone.com/javadoc/com/codename1/ui/geom/Rectangle.html

190

The Components Of Codename One

Styling The Arrow Of The Popup Dialog

One of the harder aspects of a popup dialog is the construction of the theme elements
required for arrow styling. To get that sort of behavior you will need a custom image
border and 4 arrows pointing in each direction that will be overlaid with the border.
The sizes of the arrow images should be similarly proportioned and fit
within the image borders whitespace. The block image of the dialog
should have empty pixels in the sides to reserve space for the arrow.
E.g. if the arrows are all 32x32 pixels then the PopupDialog image
should have 32 pixels of transparent pixels around it.
You will need to define the following theme constants for the arrow to work:
PopupDialogArrowBool=true
PopupDialogArrowTopImage=arrow up image
PopupDialogArrowBottomImage=arrow down image
PopupDialogArrowLeftImage=arrow left image
PopupDialogArrowRightImage=arrow right image

Then style the PopupDialog UIID with the image for the Dialog itself.

5.4.InteractionDialog
Dialogs in Codename One can be modal or modeless, the former blocks the calling
thread and the latter does not. However, there is another definition to those terms: A
modal dialog blocks access to the rest of the UI while a modeless dialog "floats" on
top of the UI.
In that sense, all dialogs in Codename One are modal; they block the parent form
since they are effectively just forms that show the "parent" in their background.
19
20
InteractionDialog has an API that is very similar to the Dialog API but, unlike dialog,
it never blocks anything. Neither the calling thread nor the UI.
InteractionDialog isnt a Dialog since it doesnt share
the same inheritance hierarchy. However, it acts and "feels" like
a Dialog despite the fact that its just a Container in the
LayeredPane .
19
20

https://www.codenameone.com/javadoc/com/codename1/components/InteractionDialog.html
https://www.codenameone.com/javadoc/com/codename1/ui/Dialog.html

191

The Components Of Codename One

InteractionDialog is really just a container that is positioned within the layered
pane. Notice that because of that design, you can have only one such dialog at the
moment and, if you add something else to the layered pane, you might run into trouble.
Using the interaction dialog is pretty trivial and very similar to dialog:
InteractionDialog dlg = new InteractionDialog("Hello");
dlg.setLayout(new BorderLayout());

dlg.add(BorderLayout.CENTER, new Label("Hello Dialog"));

Button close = new Button("Close");

close.addActionListener((ee) -> dlg.dispose());

dlg.addComponent(BorderLayout.SOUTH, close);
Dimension pre = dlg.getContentPane().getPreferredSize();
dlg.show(0, 0, Display.getInstance().getDisplayWidth() - (pre.getWidth() +
pre.getWidth() / 6), 0);

192

The Components Of Codename One

Figure 5.10. Interaction Dialog

This will show the dialog on the right hand side of the screen, which is pretty useful
for a floating in place dialog.
The InteractionDialog can only be shown at absolute or
popup locations. This is inherent to its use case which is "nonblocking". When using this component you need to be very aware
of its location.

193

The Components Of Codename One

5.5.Label
Label

21

represents a text, icon or both. Label is also the base class of Button

which in turn is the base class for RadioButton & CheckBox . Thus the functionality
of the Label class extends to all of these components.
Label text can be positioned in one of 4 locations as such:
Label left = new Label("Left", icon);
left.setTextPosition(Component.LEFT);

Label right = new Label("Right", icon);

right.setTextPosition(Component.RIGHT);

Label bottom = new Label("Bottom", icon);

bottom.setTextPosition(Component.BOTTOM);
Label top = new Label("Top", icon);

top.setTextPosition(Component.TOP);
hi.add(left).add(right).add(bottom).add(top);

21

https://www.codenameone.com/javadoc/com/codename1/ui/Label.html

194

The Components Of Codename One

Figure 5.11. Label positions

Label allows only a single line of text, line breaking is a very expensive operation on
22
mobile devices
and so the Label class doesnt support it.
SpanLabel supports multiple lines with a single label, notice that it
does carry a performance penalty for this functionality.

22

String width is the real expensive part here, the complexity of font kerning and the recursion required to

reflow text is a big performance hurdle

195

The Components Of Codename One

Labels support tickering and the ability to end with if there isnt enough space to
render the label. Developers can determine the placement of the label relatively to its
icon in quite a few powerful ways.

5.6.TextField & TextArea

23

The TextField class derives from the TextArea

input in Codename One.

24

class, and both are used for text

TextArea defaults to multi-line input and TextField defaults to single line input
but both can be used in both cases. The main differences between TextField and
TextArea are:
Blinking cursor is rendered on TextField only
DataChangeListener

25

is only available in TextField . This is crucial for character

by character input event tracking

Done listener

26

is only available in the TextField

Different UIID
The semantic difference between TextField & TextArea dates
back to the ancestor of Codename One: LWUIT. Feature phones
dont have proper in-place editing capabilities & thus TextField
was introduced to allow such input.
Because it lacks the blinking cursor capability TextArea is often used as a multi-line
label and is used internally in SpanLabel , SpanButton etc.
A common use case is to have an important text
component in edit mode immediately as we enter a Form .
Codename One forms support this exact use case thru the
Form.setEditOnShow(TextArea)

27

method.

TextField & TextArea support constraints for various types of input such as
NUMERIC , EMAIL , URL , etc. Those usually affect the virtual keyboard used, but
23

https://www.codenameone.com/javadoc/com/codename1/ui/TextField.html
24
https://www.codenameone.com/javadoc/com/codename1/ui/TextArea.html
25
https://www.codenameone.com/javadoc/com/codename1/ui/events/DataChangedListener.html
26
https://www.codenameone.com/javadoc/com/codename1/ui/TextField.html#setDoneListenercom.codename1.ui.events.ActionListener27
https://www.codenameone.com/javadoc/com/codename1/ui/Form.html#setEditOnShowcom.codename1.ui.TextArea-

196

The Components Of Codename One

might not limit input in some platforms. E.g. on iOS even with NUMERIC constraint you
would still be able to input characters.
If you need to prevent specific types of input check out the validation
section.
The following sample shows off simple text field usage:
TableLayout tl;

int spanButton = 2;

if(Display.getInstance().isTablet()) {
tl = new TableLayout(7, 2);

} else {

tl = new TableLayout(14, 1);

spanButton = 1;

}
tl.setGrowHorizontally(true);
hi.setLayout(tl);
TextField firstName = new TextField("", "First Name", 20, TextArea.ANY);
TextField surname = new TextField("", "Surname", 20, TextArea.ANY);

TextField email = new TextField("", "E-Mail", 20, TextArea.EMAILADDR);

TextField url = new TextField("", "URL", 20, TextArea.URL);

TextField phone = new TextField("", "Phone", 20, TextArea.PHONENUMBER);

TextField num1 = new TextField("", "1234", 4, TextArea.NUMERIC);
TextField num2 = new TextField("", "1234", 4, TextArea.NUMERIC);
TextField num3 = new TextField("", "1234", 4, TextArea.NUMERIC);
TextField num4 = new TextField("", "1234", 4, TextArea.NUMERIC);
Button submit = new Button("Submit");

TableLayout.Constraint cn = tl.createConstraint();
cn.setHorizontalSpan(spanButton);
cn.setHorizontalAlign(Component.RIGHT);
hi.add("First Name").add(firstName).
add("Surname").add(surname).
add("E-Mail").add(email).
add("URL").add(url).
add("Phone").add(phone).
add("Credit Card").
add(GridLayout.encloseIn(4, num1, num2, num3, num4)).
add(cn, submit);

197

The Components Of Codename One

Figure 5.12. Simple text component sample

The Toolbar section contains a very elaborate TextField search
sample with DataChangeListener and rather unique styling.

5.6.1.Masking
A common use case when working with text components is the ability to "mask" input
e.g. in the credit card number above we would want 4 digits for each text field and dont
want the user to tap Next 3 times.

198

The Components Of Codename One

Masking allows us to accept partial input in one field and implicitly move to the next,
this can be used to all types of complex input thanks to the text component API. E.g
with the code above we can mask the credit card input so the cursor jumps to the next
field implicitly using this code:
automoveToNext(num1, num2);
automoveToNext(num2, num3);
automoveToNext(num3, num4);

Then implement the method automoveToNext as:

private void automoveToNext(final TextField current, final TextField next)
{

current.addDataChangeListener((type, index) -> {

if(current.getText().length() == 5) {

});

current.stopEditing();
String val = current.getText();
current.setText(val.substring(0, 4));
next.setText(val.substring(4));
next.startEditing();

5.6.2.The Virtual Keyboard

A common misconception for developers is assuming the virtual keyboard represents
"keys". E.g. developers often override the "keyEvent" callbacks which are invoked for
physical keyboard typing and expect those to occur with a virtual keyboard.
This isnt the case since a virtual keyboard is a very different beast. With a virtual
keyboard characters typed might produce a completely different output due to
autocorrect. Some keyboards dont even have "keys" in the traditional sense or dont
type them in the traditional sense (e.g. swiping).
The constraint property for the TextField / TextArea is crucial
for a virtual keyboard.
When working with a virtual keyboard its important that the
parent Container for the TextField / TextArea is scrollable.

199

The Components Of Codename One

Otherwise the component wont be reachable or the UI might be
distorted when the keyboard appears.

Action Button Client Property

By default, the virtual keyboard on Android has a "Done" button, you can customize it
to be a search icon, a send icon, or a go icon using a hint such as this:
searchTextField.putClientProperty("searchField", Boolean.TRUE);
sendTextField.putClientProperty("sendButton", Boolean.TRUE);
goTextField.putClientProperty("goButton", Boolean.TRUE);

This will adapt the icon for the action on the keys.

Next & Done on iOS

We try to hide a lot of the platform differences in Codename One, input is very different
between OSs. A common reliance is the ability to send the "Done" event when the user
presses the Done button. Unfortunately this button doesnt always exist e.g. if there is
an Enter button (due to multiline input) or if there is a Next button in that place.
To make the behavior more uniform we slightly customized the iOS keyboard as such:

Figure 5.13. Next virtual keyboard with toolbar

200

The Components Of Codename One

Figure 5.14. Done virtual keyboard without toolbar

This works with 3rd party keyboards too

However, this behavior might not be desired so to block that we can do:
tf.putClientProperty("iosHideToolbar", Boolean.TRUE);

This will hide the toolbar for that given field.

5.7.Button
28

Button is a subclass of Label and as a result it inherits all of its functionality,

specifically icon placement, tickering, etc.
Button adds to the mix some additional states such as a pressed UIID state and
pressed icon.
There are additional icon states in Button such as rollover and
disabled icon.
Button also exposes some functionality for subclasses specifically the setToggle
method call which has no meaning when invoked on a Button but has a lot of
implications for CheckBox & RadioButton .
Button event handling can be performed via an ActionListener
30
Command .
28
29
30

https://www.codenameone.com/javadoc/com/codename1/ui/Button.html
https://www.codenameone.com/javadoc/com/codename1/ui/events/ActionListener.html
https://www.codenameone.com/javadoc/com/codename1/ui/Command.html

201

29

or via a

The Components Of Codename One

Changes in a Command wont be reflected into the Button after
the command was set to the Button .
Here is a trivial hello world style Button :
Form hi = new Form("Button");

Button b = new Button("My Button");

hi.add(b);
b.addActionListener((e) -> Log.p("Clicked"));

Figure 5.15. Simple button in the iOS styling, notice iOS doesnt
have borders on buttons
Such a button can be styled to look like a link using code like this or simply by making
these settings in the theme and using code such as btn.setUIID("Hyperlink") .
Form hi = new Form("Button");

Button b = new Button("Link Button");

b.getAllStyles().setBorder(Border.createEmpty());
b.getAllStyles().setTextDecoration(Style.TEXT_DECORATION_UNDERLINE);
hi.add(b);
b.addActionListener((e) -> Log.p("Clicked"));

31
Figure
5.16. Button styled to look like a link
https://www.codenameone.com/javadoc/com/codename1/ui/CheckBox.html
32

https://www.codenameone.com/javadoc/com/codename1/ui/RadioButton.html

202

The Components Of Codename One

5.8.CheckBox/RadioButton
CheckBox

31

& RadioButton

32

are subclasses of button that allow for either a toggle

state or exclusive selection state.

Both CheckBox & RadioButton have a selected state that allows us to determine
their selection.
RadioButton doesnt allow us to "deselect" it, the only
way to "deselect" a RadioButton is by selecting another
RadioButton .
The CheckBox can be added to a Container like any other Component but the
RadioButton must be associated with a ButtonGroup otherwise if we have more
than one set of RadioButtons in the form we might have an issue.

Notice in the sample below that we associate all the radio buttons with a group but dont
do anything with the group as the radio buttons keep the reference internally. We also
show the opposite side functionality and icon behavior:
CheckBox cb1 = new CheckBox("CheckBox No Icon");
cb1.setSelected(true);

CheckBox cb2 = new CheckBox("CheckBox With Icon", icon);

CheckBox cb3 = new CheckBox("CheckBox Opposite True", icon);

CheckBox cb4 = new CheckBox("CheckBox Opposite False", icon);

cb3.setOppositeSide(true);
cb4.setOppositeSide(false);

RadioButton rb1 = new RadioButton("Radio 1");

RadioButton rb2 = new RadioButton("Radio 2");

RadioButton rb3 = new RadioButton("Radio 3", icon);

new ButtonGroup(rb1, rb2, rb3);

rb2.setSelected(true);
hi.add(cb1).add(cb2).add(cb3).add(cb4).add(rb1).add(rb2).add(rb3);

203

The Components Of Codename One

Figure 5.17. RadioButton & CheckBox usage

Both of these components can be displayed as toggle buttons (see the toggle button
section below), or just use the default check mark/filled circle appearance based on
the type/OS.

5.8.1.Toggle Button
A toggle button is a button that is pressed and stays pressed. When a toggle button is
pressed again its released from the pressed state. Hence the button has a selected
state to indicate if its pressed or not exactly like the CheckBox / RadioButton
components in Codename One.
204

The Components Of Codename One

To turn any CheckBox or RadioButton to a toggle button just use the
setToggle(true) method. Alternatively you can use the static createToggle
method on both CheckBox and RadioButton to create a toggle button directly.

Invoking setToggle(true) implicitly converts the UIID to

ToggleButton unless it was changed by the user from its original
default value.
We can easily convert the sample above to use toggle buttons as such:
CheckBox cb1 = CheckBox.createToggle("CheckBox
cb1.setSelected(true);
CheckBox cb2 = CheckBox.createToggle("CheckBox
CheckBox cb3 = CheckBox.createToggle("CheckBox
CheckBox cb4 = CheckBox.createToggle("CheckBox
cb3.setOppositeSide(true);
cb4.setOppositeSide(false);
ButtonGroup bg = new ButtonGroup();

No Icon");
With Icon", icon);
Opposite True", icon);
Opposite False", icon);

RadioButton rb1 = RadioButton.createToggle("Radio 1", bg);

RadioButton rb2 = RadioButton.createToggle("Radio 2", bg);
RadioButton rb3 = RadioButton.createToggle("Radio 3", icon, bg);
rb2.setSelected(true);
hi.add(cb1).add(cb2).add(cb3).add(cb4).add(rb1).add(rb2).add(rb3);

205

The Components Of Codename One

Figure 5.18. Toggle button converted sample

Thats half the story though, to get the full effect of some cool toggle button UIs we
33
can use a ComponentGroup . This allows us to create a button bar effect with the
toggle buttons.
E.g. lets enclose the CheckBox components in a vertical ComponentGroup and the
RadioButtons in a horizontal group. We can do this by changing the last line of
the code above as such:

33

https://www.codenameone.com/javadoc/com/codename1/ui/ComponentGroup.html

206

The Components Of Codename One

hi.add(ComponentGroup.enclose(cb1, cb2, cb3, cb4)).

add(ComponentGroup.encloseHorizontal(rb1, rb2, rb3));

Figure 5.19. Toggle button converted sample wrapped in

ComponentGroup

207

The Components Of Codename One

5.9.ComponentGroup
ComponentGroup
(BoxLayout

35

34

is a special container that can be either horizontal or vertical

X_AXIS or Y_AXIS respectively).

ComponentGroup "restyles" the elements within the group to have a UIID that
allows us to create a "round border" effect that groups elements together.
The following code adds 4 component groups to a Container to demonstrate the
various UIID changes:
hi.add("Three Labels").

add(ComponentGroup.enclose(new Label("GroupElementFirst

UIID"), new Label("GroupElement UIID"), new Label("GroupElementLast

UIID"))).
add("One Label").

add(ComponentGroup.enclose(new Label("GroupElementOnly UIID"))).

add("Three Buttons").

add(ComponentGroup.enclose(new Button("ButtonGroupFirst

UIID"), new Button("ButtonGroup UIID"), new Button("ButtonGroupLast

UIID"))).
add("One Button").

add(ComponentGroup.enclose(new Button("ButtonGroupOnly UIID")));

34
35

https://www.codenameone.com/javadoc/com/codename1/ui/ComponentGroup.html
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/BoxLayout.html

208

The Components Of Codename One

209

Figure 5.20. ComponentGroup adapts the UIIDs of the components

The Components Of Codename One

Notice the following about the code above and the resulting image:
Buttons have a different UIID than other element types. Their styling is slightly
different in such UIs so you need to pay attention to that.
When an element is placed alone within a ComponentGroup its a special case
UIID .
By default, ComponentGroup does nothing. You need to explicitly
activate it in the theme by setting a theme property to true.
Specifically you need to set ComponentGroupBool to true for
ComponentGroup to do something otherwise its just a box layout
container! The ComponentGroupBool flag is true by default in the
iOS native theme.
When ComponentGroupBool is set to true, the component group will modify the
styles of all components placed within it to match the element UIID given to it
(GroupElement by default) with special caveats to the first/last/only elements. E.g.
1. If I have one element within a component group it will have the UIID:
GroupElementOnly
2. If I have two elements within a component group they will have the UIIDs
GroupElementFirst , GroupElementLast
3. If I have three elements within a component group they will have the UIIDs
GroupElementFirst , GroupElement , GroupElementLast
4. If I have four elements within a
the UIIDs
GroupElementFirst ,
GroupElementLast

component group they will have

GroupElement ,
GroupElement ,

This allows you to define special styles for the edges.

You
can
customize
the
UIID
set
by
the
component
group
by
calling
setElementUIID
in
the
component
group
e.g.
setElementUIID("ToggleButton") for three elements result in the following
UIIDs :
ToggleButtonFirst , ToggleButton , ToggleButtonLast

210

The Components Of Codename One

5.10.MultiButton
36

MultiButton is a composite component (lead component) that acts like a versatile

37
Button . It supports up to 4 lines of text (it doesnt automatically wrap the text), an
emblem (usually navigational arrow, or check box) and an icon.
MultiButton can be used as a button, a CheckBox or a RadioButton for

creating rich UIs.

The MultiButton was inspired by the aesthetics of the

UITableView iOS component.
A common source of confusion in the MultiButton is the difference between the icon
and the emblem, since both may have an icon image associated with them. The icon is
an image representing the entry while the emblem is an optional visual representation
of the action that will be undertaken when the element is pressed. Both may be used
simultaneously or individually of one another.
MultiButton twoLinesNoIcon = new MultiButton("MultiButton");
twoLinesNoIcon.setTextLine2("Line 2");

MultiButton oneLineIconEmblem = new MultiButton("Icon + Emblem");

oneLineIconEmblem.setIcon(icon);
oneLineIconEmblem.setEmblem(emblem);

MultiButton twoLinesIconEmblem = new MultiButton("Icon + Emblem");

twoLinesIconEmblem.setIcon(icon);
twoLinesIconEmblem.setEmblem(emblem);
twoLinesIconEmblem.setTextLine2("Line 2");

MultiButton twoLinesIconEmblemHorizontal = new MultiButton("Icon +

Emblem");
twoLinesIconEmblemHorizontal.setIcon(icon);
twoLinesIconEmblemHorizontal.setEmblem(emblem);
twoLinesIconEmblemHorizontal.setTextLine2("Line 2 Horizontal");
twoLinesIconEmblemHorizontal.setHorizontalLayout(true);
MultiButton twoLinesIconCheckBox = new MultiButton("CheckBox");
twoLinesIconCheckBox.setIcon(icon);
twoLinesIconCheckBox.setCheckBox(true);
twoLinesIconCheckBox.setTextLine2("Line 2");

36
37

https://www.codenameone.com/javadoc/com/codename1/components/MultiButton.html
https://www.codenameone.com/javadoc/com/codename1/ui/Button.html

211

The Components Of Codename One

MultiButton fourLinesIcon = new MultiButton("With Icon");
fourLinesIcon.setIcon(icon);
fourLinesIcon.setTextLine2("Line 2");
fourLinesIcon.setTextLine3("Line 3");
fourLinesIcon.setTextLine4("Line 4");

hi.add(oneLineIconEmblem).
add(twoLinesNoIcon).
add(twoLinesIconEmblem).
add(twoLinesIconEmblemHorizontal).
add(twoLinesIconCheckBox).
add(fourLinesIcon);

212

The Components Of Codename One

Figure 5.21. Multiple usage scenarios for the MultiButton

5.10.1.Styling The MultiButton

Since the MultiButton is a composite component setting its UIID will only impact
the top level UI.
To customize everything you need to customize the UIIDs for MultiLine1 ,
MultiLine2 , MultiLine3 , MultiLine4 & Emblem .

213

The Components Of Codename One

You can customize the individual UIIDs thru the API directly using
the
setIconUIID ,
setUIIDLine1 ,
setUIIDLine2 ,
setUIIDLine3 ,
setUIIDLine4 & setEmblemUIID .

5.11.SpanButton
SpanButton

38

is a composite component (lead component) that looks/acts like a

Button but can break lines rather than crop them when the text is very long.
Unlike the MultiButton it uses the TextArea internally to break lines seamlessly.
The SpanButton is far simpler than the MultiButton and as a result isnt as
configurable.
SpanButton sb = new SpanButton("SpanButton is a composite component (lead
component) that looks/acts like a Button but can break lines rather than
crop them when the text is very long.");
sb.setIcon(icon);
hi.add(sb);

Figure 5.22. The SpanButton Component

SpanButton is slower than both Button and MultiButton .
We recommend using it only when there is a genuine need for its
functionality.

5.12.SpanLabel
39

SpanLabel
is a composite component (lead component) that looks/acts like a
40
Label but can break lines rather than crop them when the text is very long.
38
39
40

https://www.codenameone.com/javadoc/com/codename1/components/SpanButton.html
https://www.codenameone.com/javadoc/com/codename1/components/SpanLabel.html
https://www.codenameone.com/javadoc/com/codename1/ui/Label.html

214

The Components Of Codename One

SpanLabel uses the TextArea internally to break lines seamlessly and so doesnt
provide all the elaborate configuration options of Label .
One of the features of label that moved into SpanLabel to some extent is the ability

to position the icon. However, unlike a Label the icon position is determined by the
layout manager of the composite so setIconPosition accepts a BorderLayout
constraint.
SpanLabel d = new SpanLabel("Default SpanLabel that can seamlessly line
break when the text is really long.");
d.setIcon(icon);

SpanLabel l = new SpanLabel("NORTH Positioned Icon SpanLabel that can

seamlessly line break when the text is really long.");
l.setIcon(icon);
l.setIconPosition(BorderLayout.NORTH);

SpanLabel r = new SpanLabel("SOUTH Positioned Icon SpanLabel that can

seamlessly line break when the text is really long.");
r.setIcon(icon);
r.setIconPosition(BorderLayout.SOUTH);

SpanLabel c = new SpanLabel("EAST Positioned Icon SpanLabel that can

seamlessly line break when the text is really long.");
c.setIcon(icon);
c.setIconPosition(BorderLayout.EAST);
hi.add(d).add(l).add(r).add(c);

215

The Components Of Codename One

Figure 5.23. The SpanLabel Component

SpanLabel is significantly slower than Label . We recommend
using it only when there is a genuine need for its functionality.

5.13.OnOffSwitch
41

The OnOffSwitch allows you to write an application where the user can swipe a
switch between two states (on/off). This is a common UI paradigm in Android and iOS,
although its implemented in a radically different way in both platforms.
41

https://www.codenameone.com/javadoc/com/codename1/components/OnOffSwitch.html

216

The Components Of Codename One

This is a rather elaborate component because of its very unique design on iOS, but
we were able to accommodate most of the small behaviors of the component into our
version, and it seamlessly adapts between the Android style and the iOS style.
The image below was generated based on the default use of the OnOffSwitch :
OnOffSwitch onOff = new OnOffSwitch();
hi.add(onOff);

Figure 5.24. The OnOffSwitch component as it appears on/off on

iOS (top) and on Android (bottom)
As you can understand the difference between the way iOS and Android render this
component has triggered two very different implementations within a single component.
217

The Components Of Codename One

The Android implementation just uses standard buttons and is the default for non-iOS
platforms.
You can force the Android or iOS mode by using the theme constant
onOffIOSModeBool .

5.13.1.Validation
42

Validation is an inherent part of text input, and the Validator class allows just that.
You can enable validation thru the Validator class to add constraints for a specific
component. Its also possible to define components that would be enabled/disabled
based on validation state and the way in which validation errors are rendered (change
43
the components UIID , paint an emblem on top, etc.). A Constraint is an interface
that represents validation requirements. You can define a constraint in Java or use
44
45
some of the builtin constraints such as LengthConstraint , RegexConstraint , etc.
This sample below continues from the place where the TextField sample above stopped
by adding validation to that code.
Validator v = new Validator();

v.addConstraint(firstName, new LengthConstraint(2)).

addConstraint(surname, new LengthConstraint(2)).

addConstraint(url, RegexConstraint.validURL()).
addConstraint(email, RegexConstraint.validEmail()).

addConstraint(phone, new RegexConstraint(phoneRegex, "Must be

valid phone number")).

addConstraint(num1, new LengthConstraint(4)).

addConstraint(num2, new LengthConstraint(4)).
addConstraint(num3, new LengthConstraint(4)).
addConstraint(num4, new LengthConstraint(4));

v.addSubmitButtons(submit);

42
https://www.codenameone.com/javadoc/com/codename1/ui/validation/Validator.html
43
https://www.codenameone.com/javadoc/com/codename1/ui/validation/Constraint.html
44
https://www.codenameone.com/javadoc/com/codename1/ui/validation/LengthConstraint.html
45
https://www.codenameone.com/javadoc/com/codename1/ui/validation/RegexConstraint.html

218

The Components Of Codename One

Figure 5.25. Validation & Regular Expressions

5.14.InfiniteProgress
46

The InfiniteProgress indicator spins an image infinitely to indicate that a background

process is still working.
This style of animation is often nicknamed "washing machine" as it
spins endlessly.
46

https://www.codenameone.com/javadoc/com/codename1/components/InfiniteProgress.html

219

The Components Of Codename One

InfiniteProgress can be used in one of two ways either by embedding the
component into the UI thru something like this:
myContainer.add(new InfiniteProgress());

InfiniteProgress can also appear over the entire screen, thus blocking all input.
This tints the background while the infinite progress rotates:
Dialog ip = new InfiniteProgress().showInifiniteBlocking();
// do some long operation here using invokeAndBlock or do something in a
separate thread and callback later

// when you are done just call

ip.dispose();

Figure 5.26. Infinite progress

The image used in the InfiniteProgress animation is defined by the native
theme. You can override that definition either by defining the theme constant
47
infiniteImage or by invoking the setAnimation method.
Despite the name of the method setAnimation expects a static
image that will be rotated internally. Dont use an animated image.
47

https://www.codenameone.com/javadoc/com/codename1/components/

InfiniteProgress.html#setAnimation-com.codename1.ui.Image-

220

The Components Of Codename One

5.15.InfiniteScrollAdapter & InfiniteContainer

InfiniteScrollAdapter

48

& InfiniteContainer

49

allow us to create a scrolling effect that

"never" ends with the typical Container / Component paradigm.

The motivation behind these classes is simple, say we have a lot of data to fetch from
storage or from the internet. We can fetch the data in batches and show progress
indication while we do this.
Infinite scroll fetches the next batch of data dynamically as we reach the end of the
Container . InfiniteScrollAdapter & InfiniteContainer represent two
similar ways to accomplish that task relatively easily.
Let start by exploring how we can achieve this UI that fetches data from a webservice:

48
49

https://www.codenameone.com/javadoc/com/codename1/components/InfiniteScrollAdapter.html
https://www.codenameone.com/javadoc/com/codename1/ui/InfiniteContainer.html

221

The Components Of Codename One

Figure 5.27. InfiniteScrollAdapter demo code fetching property

cross data
The first step is creating the webservice call, we wont go into too much detail here as
webservices & IO are discussed later in the guide:
int pageNumber = 1;

java.util.List<Map<String, Object>> fetchPropertyData(String text) {

try {

ConnectionRequest r = new ConnectionRequest();

r.setPost(false);
r.setUrl("http://api.nestoria.co.uk/api");

222

The Components Of Codename One

r.addArgument("pretty", "0");

r.addArgument("action", "search_listings");
r.addArgument("encoding", "json");
r.addArgument("listing_type", "buy");

r.addArgument("page", "" + pageNumber);

pageNumber++;
r.addArgument("country", "uk");
r.addArgument("place_name", text);
NetworkManager.getInstance().addToQueueAndWait(r);

Map<String,Object> result = new JSONParser().parseJSON(new

InputStreamReader(new

ByteArrayInputStream(r.getResponseData()), "UTF-8"));
Map<String, Object> response = (Map<String,
Object>)result.get("response");
return (java.util.List<Map<String,

Object>>)response.get("listings");
} catch(Exception err) {
Log.e(err);

return null;

The demo code here doesnt do any error handling! This is a very
bad practice and it is taken here to keep the code short and readable.
Proper error handling is used in the Property Cross demo.
The fetchPropertyData is a very simplistic tool that just fetches the next page of
listings for the nestoria webservice. Notice that this method is synchronous and will
block the calling thread (legally) until the network operation completes.
Now that we have a webservice lets proceed to create the UI. Check out the code
annotations below:
Form hi = new Form("InfiniteScrollAdapter", new
BoxLayout(BoxLayout.Y_AXIS));

Style s = UIManager.getInstance().getComponentStyle("MultiLine1");
FontImage p = FontImage.createMaterial(FontImage.MATERIAL_PORTRAIT, s);
EncodedImage placeholder =
EncodedImage.createFromImage(p.scaled(p.getWidth() * 3, p.getHeight()
* 3), false);
InfiniteScrollAdapter.createInfiniteScroll(hi.getContentPane(), () -> {

223

The Components Of Codename One

java.util.List<Map<String, Object>> data =
fetchPropertyData("Leeds");

MultiButton[] cmps = new MultiButton[data.size()];

for(int iter = 0 ; iter < cmps.length ; iter++) {

Map<String, Object> currentListing = data.get(iter);

if(currentListing == null) {

InfiniteScrollAdapter.addMoreComponents(hi.getContentPane(), new
Component[0], false);
return;

}
String thumb_url = (String)currentListing.get("thumb_url");
String guid = (String)currentListing.get("guid");
String summary = (String)currentListing.get("summary");
cmps[iter] = new MultiButton(summary);

cmps[iter].setIcon(URLImage.createToStorage(placeholder, guid,
thumb_url));
}
InfiniteScrollAdapter.addMoreComponents(hi.getContentPane(), cmps,
true);
}, true);
50

Placeholder is essential for the URLImage class which we will discuss at a

different place.
The InfiniteScrollAdapter accepts a runnable which is invoked every time
we reach the edge of the scrolling. We used a closure instead of the typical run()
method override.
This is a blocking call, after the method completes well have all the data we need.
Notice that this method doesnt block the EDT illegally.
If there is no more data we call the addMoreComponents method with a false
argument. This indicates that there is no additional data to fetch.
Here we add the actual components to the end of the form. Notice that we must
not invoke the add / remove method of Container . Those might conflict with
the work of the InfiniteScrollAdapter .
We pass true to indicate that the data isnt "prefilled" so the method should be
invoked immediately when the Form is first shown
Do not violate the EDT in the callback. It is invoked on the event
dispatch thread and it is crucial
50

https://www.codenameone.com/javadoc/com/codename1/ui/URLImage.html

224

The Components Of Codename One

5.15.1.The InfiniteContainer
51

InfiniteContainer was introduced to simplify and remove some of the boilerplate of

the InfiniteScrollAdapter . It takes a more traditional approach of inheriting the
Container class to provide its functionality.
Unlike the InfiniteScrollAdapter the InfiniteContainer accepts an index
and amount to fetch. This is useful for tracking your position but also important since
the InfiniteContainer also implements Pull To Refresh as part of its functionality.
Converting the code above to an InfiniteContainer is pretty simple we just
moved all the code into the callback fetchComponents method and returned the
array of Components as a response.
Unlike the InfiniteScrollAdapter we cant use the ContentPane directly so
we have to use a BorderLayout and place the InfiniteContainer there:
Form hi = new Form("InfiniteContainer", new BorderLayout());
Style s = UIManager.getInstance().getComponentStyle("MultiLine1");
FontImage p = FontImage.createMaterial(FontImage.MATERIAL_PORTRAIT, s);
EncodedImage placeholder =
EncodedImage.createFromImage(p.scaled(p.getWidth() * 3, p.getHeight()
* 3), false);
InfiniteContainer ic = new InfiniteContainer() {
@Override

public Component[] fetchComponents(int index, int amount) {

java.util.List<Map<String, Object>> data =

fetchPropertyData("Leeds");

MultiButton[] cmps = new MultiButton[data.size()];

for(int iter = 0 ; iter < cmps.length ; iter++) {

Map<String, Object> currentListing = data.get(iter);

if(currentListing == null) {
return null;

}
String thumb_url = (String)currentListing.get("thumb_url");
String guid = (String)currentListing.get("guid");
String summary = (String)currentListing.get("summary");
cmps[iter] = new MultiButton(summary);

cmps[iter].setIcon(URLImage.createToStorage(placeholder, guid,
thumb_url));
51

https://www.codenameone.com/javadoc/com/codename1/ui/InfiniteContainer.html

225

The Components Of Codename One

}
}

return cmps;

};
hi.add(BorderLayout.CENTER, ic);

5.16.List, MultiList, Renderers & Models

5.16.1.InfiniteContainer/InfiniteScrollAdapter vs. List/
ContainerList
Our recommendation is to always go with Container , InfiniteContainer or
InfiniteScrollAdapter .
We recommend avoiding List or its subclasses/related classes specifically
ContainerList & MultiList .
We recommend replacing ComboBox with Picker but thats a
completely different discussion.
A Container with ~5000 nested containers within it can perform on par with a List
and probably exceed its performance when used correctly.
Larger sets of data are rarely manageable on phones or tablets so the benefits for lists
are dubious.
In terms of API we found that even experienced developers experienced a great deal
of pain when wrangling the Swing styled lists and their stateless approach.
Since animation, swiping and other capabilities that are so common in mobile are so
hard to accomplish with lists we see no actual reason to use them.

5.16.2.Why Isnt List Deprecated?

We deprecated ContainerList which performs really badly and has some inherent
complexity issues. List has some unique use cases and is still used all over
Codename One.
MultiList is a reasonable version of List that is far easier to use without most of
the pains related to renderer configuration.
226

The Components Of Codename One

There are cases where using List or MultiList is justified, they are just rarer than
usual hence our recommendation.

5.16.3.MVC In Lists
52

A Codename One List doesnt contain components, but rather arbitrary data; this
seems odd at first but makes sense. If you want a list to contain components, just use
a Container.
The advantage of using a List in this way is that we can display it in many ways
(e.g. fixed focus positions, horizontally, etc.), and that we can have more than a million
entries without performance overhead. We can also do some pretty nifty things, like
filtering the list on the fly or fetching it dynamically from the Internet as the user scrolls
53
down the list. To achieve these things the list uses two interfaces: ListModel and
54

ListCellRenderer. List model represents the data; its responsibility is to return the
arbitrary object within the list at a given offset. Its second responsibility is to notify the
list when the data changes, so the list can refresh.
Think of the model as an array of objects that can notify you when
it changes.
The list renderer is like a rubber stamp that knows how to draw an object from the
model, its called many times per entry in an animated list and must be very fast. Unlike
standard Codename One components, it is only used to draw the entry in the model
and is immediately discarded, hence it has no memory overhead, but if it takes too long
to process a model value it can be a big bottleneck!
Think of the render as a translation layer that takes the "data" from
the model and translates it to a visual representation.
This is all very generic, but a bit too much for most, doing a list "properly" requires some
understanding. The main source of confusion for developers is the stateless nature of
the list and the transfer of state to the model (e.g. a checkbox list needs to listen to
action events on the list and update the model, in order for the renderer to display that
state). Once you understand that its easy.
52
53
54

https://www.codenameone.com/javadoc/com/codename1/ui/List.html
https://www.codenameone.com/javadoc/com/codename1/ui/list/ListModel.html
https://www.codenameone.com/javadoc/com/codename1/ui/List.html

227

The Components Of Codename One

5.16.4.Understanding MVC
Lets recap, what is MVC:
Model - Represents the data for the component (list), the model can tell us exactly
how many items are in it and which item resides at a given offset within the model.
This differs from a simple Vector (or array), since all access to the model is
controlled (the interface is simpler), and unlike a Vector /Array, the model can
notify us of changes that occur within it.
View - The view draws the content of the model. It is a "dumb" layer that has no
notion of what is displayed and only knows how to draw. It tracks changes in the
model (the model sends events) and redraws itself when it changes.
Controller - The controller accepts user input and performs changes to the model,
which in turn cause the view to refresh.

228

The Components Of Codename One

Figure 5.28. Typical MVC Diagram

55

56

Codename Ones List component uses the MVC paradigm in its implementation.
57
List itself is the Controller (with a bit of the View mixed in). The ListCellRenderer
55

Image by RegisFrey - Own work, Public Domain, https://commons.wikimedia.org/w/index.php?

curid=10298177
56
https://www.codenameone.com/javadoc/com/codename1/ui/List.html

229

The Components Of Codename One

interface is the rest of the View and the ListModel
Model.

58

is (you guessed it by now) the

When the list is painted, it iterates over the visible elements in the model and asks the
model for the data, it then draws them using the renderer. Notice that because of this
both the model and the renderer must be REALLY fast and thats hard.

Why is this useful?

Since the model is a lightweight interface, it can be implemented by you and replaced
in runtime if so desired, this allows several use cases:
1. A list can contain thousands of entries but only load the portion visible to the user.
Since the model will only be queried for the elements that are visible to the user,
it wont need to load the large data set into memory until the user starts scrolling
down (at which point other elements may be offloaded from memory).
2. A list can cache efficiently. E.g. a list can mirror data from the server into local RAM
without actually downloading all the data. Data can also be mirrored from storage
for better performance and discarded for better memory utilization.
3. The is no need for state copying. Since renderers allow us to display any object type,
the list model interface can be implemented by the applications data structures (e.g.
persistence/network engine), which would return internal application data structures
saving you the need of copying application state into a list specific data structure.
Note that this advantage only applies with a custom renderer which is pretty difficult
to get right.
4. Using the proxy pattern we can layer logic such as filtering, sorting, caching, etc.
on top of existing models without changing the model source code.
5. We can reuse generic models for several views, e.g. a model that fetches data
from the server can be initialized with different arguments, to fetch different data
for different views. View objects in different Forms can display the same model
instance in different view instances, thus they would update automatically when we
change one global model.
Most of these use cases work best for lists that grow to a larger size, or represent
complex data, which is what the list object is designed to do.
57
58

https://www.codenameone.com/javadoc/com/codename1/ui/list/ListCellRenderer.html
https://www.codenameone.com/javadoc/com/codename1/ui/list/ListModel.html

230

The Components Of Codename One

5.16.5.Important - Lists & Layout Managers

Usually when working with lists, you want the list to handle the scrolling (otherwise it
will perform badly). This means you should place the list in a non-scrollable container
(no parent can be scrollable), notice that the content pane is scrollable by default, so
you should disable that.
It is also recommended to place the list in the CENTER location of a BorderLayout
to produce the most effective results. e.g.:

59

form.setScrollable(false);

form.setLayout(new BorderLayout());

form.add(BorderLayout.CENTER, myList);

5.16.6.MultiList & DefaultListModel

So after this long start lets show the first sample of creating a list using the MultiList

60

The MultiList is a preconfigured list that contains a ready made renderer with
defaults that make sense for the most common use cases. It still retains most of the
power available to the List component but reduces the complexity of one of the
hardest things to grasp for most developers: rendering.
The full power of the ListModel is still available and allows you to create a million
entry list with just a few lines of code. However the objects that the model returns should
always be in the form of Map objects and not an arbitrary object like the standard
List allows.
Here is a simple example of a MultiList containing a highly popular subject matter:
Form hi = new Form("MultiList", new BorderLayout());
ArrayList<Map<String, Object>> data = new ArrayList<>();
data.add(createListEntry("A
data.add(createListEntry("A
data.add(createListEntry("A
data.add(createListEntry("A
59
60

Game of Thrones", "1996"));

Clash Of Kings", "1998"));
Storm Of Swords", "2000"));
Feast For Crows", "2005"));

https://www.codenameone.com/javadoc/com/codename1/ui/layouts/BorderLayout.html
https://www.codenameone.com/javadoc/com/codename1/ui/list/MultiList.html

231

The Components Of Codename One

data.add(createListEntry("A Dance With Dragons", "2011"));

data.add(createListEntry("The Winds of Winter", "2016 (please, please,

please)"));
data.add(createListEntry("A Dream of Spring", "Ugh"));
DefaultListModel<Map<String, Object>> model = new
DefaultListModel<>(data);

MultiList ml = new MultiList(model);

hi.add(BorderLayout.CENTER, ml);

Figure 5.29. Basic usage of the MultiList & DefaultListModel]

createListEntry is relatively trivial:
232

The Components Of Codename One

private Map<String, Object> createListEntry(String name, String date) {

Map<String, Object> entry = new HashMap<>();
entry.put("Line1", name);
entry.put("Line2", date);
return entry;

There is one major piece missing here and that is the cover images for the books. A
simple approach would be to just place the image objects into the entries using the
"icon" property as such:
private Map<String, Object> createListEntry(String name, String date,
Image cover) {

Map<String, Object> entry = new HashMap<>();

entry.put("Line1", name);
entry.put("Line2", date);
entry.put("icon", cover);

return entry;

233

The Components Of Codename One

Figure 5.30. With cover images in place

Since the MultiList uses the GenericListCellRenderer
61
internally we can use URLImage to dynamically fetch the data.
This is discussed in the graphics section of this guide.

61

https://www.codenameone.com/javadoc/com/codename1/ui/URLImage.html

234

The Components Of Codename One

Going Further With the ListModel

62

Lets assume that GRRM was really prolific and wrote 1 million books. The default
list model wont make much sense in that case but we would still be able to render
everything in a list model.
Well fake it a bit but notice that 1M components wont be created even if we somehow
scroll all the way down
63

The ListModel interface can be implemented by anyone in this case we just did a
really stupid simple implementation:
class GRMMModel implements ListModel<Map<String,Object>> {
@Override

public Map<String, Object> getItemAt(int index) {

int idx = index % 7;
switch(idx) {
case 0:

return createListEntry("A Game of Thrones " +

index, "1996");

case 1:

return createListEntry("A Clash Of Kings " +

index, "1998");

case 2:

return createListEntry("A Storm Of Swords " +

index, "2000");

case 3:

return createListEntry("A Feast For Crows " +

index, "2005");

case 4:

return createListEntry("A Dance With Dragons " +

index, "2011");

case 5:

return createListEntry("The Winds of Winter " +

index, "2016 (please, please, please)");

default:

index, "Ugh");
}
}

62
63

return createListEntry("A Dream of Spring " +

http://www.georgerrmartin.com/
https://www.codenameone.com/javadoc/com/codename1/ui/list/ListModel.html

235

The Components Of Codename One

@Override

public int getSize() {

}

return 1000000;

@Override

public int getSelectedIndex() {

}

return 0;

@Override

public void setSelectedIndex(int index) {

}

@Override

public void addDataChangedListener(DataChangedListener l) {

}

@Override

public void removeDataChangedListener(DataChangedListener l) {

}

@Override

public void addSelectionListener(SelectionListener l) {

}

@Override

public void removeSelectionListener(SelectionListener l) {

}

@Override

public void addItem(Map<String, Object> item) {

}

@Override

public void removeItem(int index) {

}

We can now replace the existing model by removing all the model related logic and
changing the constructor call as such:
MultiList ml = new MultiList(new GRMMModel());

236

The Components Of Codename One

Figure 5.31. It took ages to scroll this far This goes to a million

5.16.7.List Cell Renderer

The Renderer is a simple interface with 2 methods:
public interface ListCellRenderer {

//This method is called by the List for each item, when the List paints

itself.

public Component getListCellRendererComponent(List list, Object

value, int index, boolean isSelected);

237

The Components Of Codename One

//This method returns the List animated focus which is animated when

list selection changes

public Component getListFocusComponent(List list);

The most simple/naive implementation may choose to implement the renderer as

follows:
public Component getListCellRendererComponent(List list, Object value, int
index, boolean isSelected){

return new Label(value.toString());

public Component getListFocusComponent(List list){

return null;

This will compile and work, but wont give you much, notice that you wont see the
64
List selection move on the List, this is just because the renderer returns a Label
with the same style regardless if its selected or not.
Now Lets try to make it a bit more useful.
public Component getListCellRendererComponent(List list, Object value, int
index, boolean isSelected){

Label l = new Label(value.toString());

if (isSelected) {

l.setFocus(true);
l.getAllStyles().setBgTransparency(100);

} else {

}
}
}

l.setFocus(false);
l.getAllStyles().setBgTransparency(0);

return l;

public Component getListFocusComponent(List list){

return null;

In this renderer we set the Label.setFocus(true) if its selected, calling to this

method doesnt really give the focus to the Label, it simply renders the label as selected.
64

https://www.codenameone.com/javadoc/com/codename1/ui/Label.html

238

The Components Of Codename One

Then we invoke Label.getAllStyles().setBgTransparency(100) to give
the selection semi transparency, and 0 for full transparency if not selected.
That is still not very efficient because we create a new Label each time the method
is invoked.
To make the code tighter, keep a reference to the Component or extend it as
65
DefaultListCellRenderer does.
class MyRenderer extends Label implements ListCellRenderer {

public Component getListCellRendererComponent(List list, Object

value, int index, boolean isSelected){

setText(value.toString());
if (isSelected) {

setFocus(true);
getAllStyles().setBgTransparency(100);

} else {

setFocus(false);
getAllStyles().setBgTransparency(0);

return this;
}

Now Lets have a look at a more advanced Renderer.

class ContactsRenderer extends Container implements ListCellRenderer {
private Label name = new Label("");

private Label email = new Label("");

private Label pic = new Label("");

private Label focus = new Label("");

public ContactsRenderer() {

setLayout(new BorderLayout());

addComponent(BorderLayout.WEST, pic);

Container cnt = new Container(new BoxLayout(BoxLayout.Y_AXIS));

name.getAllStyles().setBgTransparency(0);
name.getAllStyles().setFont(Font.createSystemFont(Font.FACE_SYSTEM,
Font.STYLE_BOLD, Font.SIZE_MEDIUM));
65

https://www.codenameone.com/javadoc/com/codename1/ui/list/DefaultListCellRenderer.html

239

The Components Of Codename One

email.getAllStyles().setBgTransparency(0);
cnt.addComponent(name);
cnt.addComponent(email);
addComponent(BorderLayout.CENTER, cnt);

focus.getStyle().setBgTransparency(100);

public Component getListCellRendererComponent(List list, Object

value, int index, boolean isSelected) {
Contact person = (Contact) value;
name.setText(person.getName());
email.setText(person.getEmail());
pic.setIcon(person.getPic());
return this;

public Component getListFocusComponent(List list) {

return focus;

In this renderer we want to render a Contact object to the Screen, we build the
Component in the constructor and in the getListCellRendererComponent we simply
update the Labels' texts according to the Contact object.
Notice that in this renderer we return a focus Label with semi transparency, as
mentioned before, the focus component can be modified within this method.
For example, I can modify the focus Component to have an icon.
focus.getAllStyles().setBgTransparency(100);
try {

focus.setIcon(Image.createImage("/duke.png"));
focus.setAlignment(Component.RIGHT);

} catch (IOException ex) {

}

ex.printStackTrace();

5.16.8.Generic List Cell Renderer

As part of the GUI builder work, we needed a way to customize rendering for
a List, but the renderer/model approach seemed impossible to adapt to a GUI
240

The Components Of Codename One

builder (it seems the Swing GUI builders had a similar issue). Our solution was to
introduce the GenericListCellRenderer , which while introducing limitations and

implementation requirements still manages to make life easier, both in the GUI builder
and outside of it.
66

GenericListCellRenderer
is a renderer designed to be as simple to use as a
Component - Container hierarchy, we effectively crammed most of the common
renderer use cases into one class. To enable that, we need to know the content of the
objects within the model, so the GenericListCellRenderer assumes the model
contains only Map objects. Since Maps can contain arbitrary data the list model is
still quite generic and allows storing application specific data. Furthermore a Map can
still be derived and extended to provide domain specific business logic.
The GenericListCellRenderer accepts two container instances (more later on
why at least two, and not one), which it maps to individual Map entries within the
model, by finding the appropriate components within the given container hierarchy.
Components are mapped to the Map entries based on the name property of the
component ( getName / setName ) and the key/value within the Map , e.g.:
For a model that contains a Map entry like this:
"Foo": "Bar"
"X": "Y"
"Not": "Applicable"
"Number": Integer(1)

A renderer will loop over the component hierarchy in the container, searching for
components whose name matches Foo, X, Not, and Number, and assigning the
appropriate value to them.
You can also use image objects as values, and they will be assigned
to labels as expected. However, you cant assign both an image and
a text to a single label, since the key will be taken. That isnt a big
problem, since two labels can be used quite easily in such a renderer.
To make matters even more attractive the renderer seamlessly supports list tickering
67
when appropriate, and if a CheckBox appears within the renderer, it will toggle a
boolean flag within the Map seamlessly.
66
67

https://www.codenameone.com/javadoc/com/codename1/ui/list/GenericListCellRenderer.html
https://www.codenameone.com/javadoc/com/codename1/ui/CheckBox.html

241

The Components Of Codename One

One issue that crops up with this approach is that, if a value is missing from the Map ,
it is treated as empty and the component is reset.
This can pose an issue if we hardcode an image or text within the renderer and we
dont want them replaced (e.g. an arrow graphic on a Label within the renderer).
The solution for this is to name the component with Fixed in the end of the name, e.g.
HardcodedIconFixed .
Naming a component within the renderer with $number will automatically set it as a
counter component for the offset of the component within the list.
Styling the GenericListCellRenderer is slightly different, the renderer uses the
UIID of the Container passed to the generic list cell renderer, and the background
focus uses that same UIID with the word "Focus" appended to it.
It is important to notice that the generic list cell renderer will grant focus to the child
components of the selected entry if they are focusable, thus changing the style of said
68
entries. E.g. a Container might have a child Label that has one style when the
parent container is unselected and another when its selected (focused), this can be
easily achieved by defining the label as focusable. Notice that the component will never
receive direct focus, since it is still part of a renderer.
Last but not least, the generic list cell renderer accepts two or four instances of a
Container, rather than the obvious choice of accepting only one instance. This allows
the renderer to treat the selected entry differently, which is especially important to
69
tickering, although its also useful for the fisheye effect . Since it might not be
practical to seamlessly clone the Container for the renderers needs, Codename
One expects the developer to provide two separate instances, they can be identical in
all respects, but they must be separate instances for tickering to work. The renderer
also allows for a fisheye effect, where the selected entry is actually different from
the unselected entry in its structure, it also allows for a pinstripe effect, where odd/
even rows have different styles (this is accomplished by providing 4 instances of the
containers selected/unselected for odd/even).
The best way to learn about the generic list cell renderer and the Map model is by
playing with them in the old GUI builder. Notice they can be used in code without any
dependency on the GUI builder and can be quite useful at that.
Here is a simple example of a list with checkboxes that gets updated automatically:
68
69

https://www.codenameone.com/javadoc/com/codename1/ui/Container.html
Fisheye is an effect where the selection stays in place as the list moves around it

242

The Components Of Codename One

com.codename1.ui.List list = new

com.codename1.ui.List(createGenericListCellRendererModelData());

list.setRenderer(new

GenericListCellRenderer(createGenericRendererContainer(),
createGenericRendererContainer()));

private Container createGenericRendererContainer() {

Label name = new Label();
name.setFocusable(true);
name.setName("Name");

Label surname = new Label();

surname.setFocusable(true);
surname.setName("Surname");

CheckBox selected = new CheckBox();

selected.setName("Selected");
selected.setFocusable(true);
Container c = BorderLayout.center(name).
add(BorderLayout.SOUTH, surname).
add(BorderLayout.WEST, selected);
c.setUIID("ListRenderer");
}

return c;

private Object[] createGenericListCellRendererModelData() {

Map<String,Object>[] data = new HashMap[5];
data[0] = new HashMap<>();

data[0].put("Name", "Shai");
data[0].put("Surname", "Almog");
data[0].put("Selected", Boolean.TRUE);
data[1] = new HashMap<>();

data[1].put("Name", "Chen");
data[1].put("Surname", "Fishbein");
data[1].put("Selected", Boolean.TRUE);
data[2] = new HashMap<>();

data[2].put("Name", "Ofir");
data[2].put("Surname", "Leitner");
data[3] = new HashMap<>();

data[3].put("Name", "Yaniv");
data[3].put("Surname", "Vakarat");
data[4] = new HashMap<>();

data[4].put("Name", "Meirav");
data[4].put("Surname", "Nachmanovitch");
return data;

243

The Components Of Codename One

}

Figure 5.32. GenericListCellRenderer demo code

Custom UIID Of Entry in GenenricListCellRenderer/MultiList

70

With MultiList / GenenricListCellRenderer one of the common issues is

making a UI where a specific component within the list renderer has a different UIID
style based on data. E.g. this can be helpful to mark a label within the list as red, for
instance, in the case of a list of monetary transactions.
70

https://www.codenameone.com/javadoc/com/codename1/ui/list/MultiList.html

244

The Components Of Codename One

This can be achieved with a custom renderer, but that is a pretty difficult task.
GenericListCellRenderer ( MultiList uses GenericListCellRenderer
internally) has another option.

Normally, to build the model for a renderer of this type, we use something like:
map.put("componentName", "Component Value");

What if we want componentName to be red? Just use:

map.put("componentName_uiid", "red");

This will apply the UIID "red" to the component, which you can then style in the theme.
Notice that once you start doing this, you need to define this entry for all entries, e.g.:
map.put("componentName_uiid", "blue");

Otherwise the component will stay red for the next entry (since the renderer acts like
a rubber stamp).

Rendering Prototype
Because of the rendering architecture of a List its pretty hard to calculate the right
preferred size for such a component. The default behavior includes querying a few
entries from the model then constructing their renderers to get a "sample" of the
preferred size value.
As you might guess this triggers a performance penalty that is paid with every reflow
of the UI. The solution is to use setRenderingPrototype .
setRenderingPrototype accepts a "fake" value that represents a reasonably
large amount of data and it will be used to calculate the preferred size. E.g. for a multiList
that should render 2 lines of text with 20 characters and a 5mm square icon I can do
something like this:
Map<String, Object> proto = new HashMap<>();
map.put("Line1", "WWWWWWWWWWWWWWWWWWWW");
map.put("Line2", "WWWWWWWWWWWWWWWWWWWW");

int mm5 = Display.getInstance().convertToPixels(5, true);

map.put("icon", Image.create(mm5, mm5));

245

The Components Of Codename One

myMultiList.setRenderingPrototype(map);

5.16.9.ComboBox
71

The ComboBox is a specialization of List that displays a single selected entry.

When clicking that entry a popup is presented allowing the user to pick an entry from
the full list of entries.
The ComboBox UI paradigm isnt as common on OSs such as iOS
where there is no native equivalent to it. We recommend using either
72
73
the Picker class or the AutoCompleteTextField .
ComboBox is notoriously hard to style properly as it relies on a complex dynamic
of popup renderer and instantly visible renderer. The UIID for the ComboBox
is ComboBox however if you set it to something else all the other UIIDs
will also change their prefix. E.g. the ComboBoxPopup UIID will become
MyNewUIIDPopup .
The combo box defines the following UIIDs by default:
ComboBox
ComboBoxItem
ComboBoxFocus
PopupContentPane
PopupItem
PopupFocus
The ComboBox also defines theme constants that allow some native themes to
manipulate its behavior e.g.:
popupTitleBool - shows the "label for" value as the title of the popup dialog
popupCancelBodyBool - Adds a cancel button into the popup dialog
centeredPopupBool - shows the popup dialog in the center of the screen instead
of under the popup
otherPopupRendererBool - Uses a different list cell render for the popup
than the one used for the ComboBox itself. When this is false PopupItem &
71
72
73

https://www.codenameone.com/javadoc/com/codename1/ui/ComboBox.html
https://www.codenameone.com/javadoc/com/codename1/ui/spinner/Picker.html
https://www.codenameone.com/javadoc/com/codename1/ui/AutoCompleteTextField.html

246

The Components Of Codename One

PopupFocus become irrelevant. Notice that the Android native theme defines this
to true .
Since a ComboBox is really a List you can use everything we learned about a List
to build a ComboBox including models, GenericListCellRenderer etc.
E.g. the demo below uses the GRRM demo data from above to build a ComboBox :
Form hi = new Form("ComboBox", new BoxLayout(BoxLayout.Y_AXIS));
ComboBox<Map<String, Object>> combo = new ComboBox<> (

createListEntry("A Game of Thrones", "1996"),

createListEntry("A Clash Of Kings", "1998"),
createListEntry("A Storm Of Swords", "2000"),
createListEntry("A Feast For Crows", "2005"),
createListEntry("A Dance With Dragons", "2011"),
createListEntry("The Winds of Winter", "2016 (please, please,
please)"),
createListEntry("A Dream of Spring", "Ugh"));

combo.setRenderer(new GenericListCellRenderer<>(new MultiButton(), new

MultiButton()));

Figure 5.33. GRRM ComboBox

5.17.Slider
74

A Slider is an empty component that can be filled horizontally or vertically to allow

indicating progress, setting volume etc. It can be editable to allow the user to determine
its value or none editable to just relay that information to the user. It can have a thumb
on top to show its current position.
74

https://www.codenameone.com/javadoc/com/codename1/ui/Slider.html

247

The Components Of Codename One

Figure 5.34. Slider

The interesting part about the slider is that it has two separate style UIIDs ,
Slider & SliderFull . The Slider UIID is always painted and SliderFull
is rendered on top based on the amount the Slider should be filled.
Slider is highly customizable e.g. a slider can be used to replicate a 5 star rating
widget as such. Notice that this slider will only work when its given its preferred size
otherwise additional stars will appear. Thats why we place it within a FlowLayout :
Form hi = new Form("Star Slider", new BoxLayout(BoxLayout.Y_AXIS));
hi.add(FlowLayout.encloseCenter(createStarRankSlider()));
hi.show();

The slider itself is initialized in the code below. Notice that you can achieve almost the
same result using a theme by setting the Slider & SliderFull UIIDs (both in
selected & unselected states).
In fact doing this in the theme might be superior as you could use one image that
contains 5 stars already and that way you wont need the preferred size hack below:
private void initStarRankStyle(Style s, Image star) {

s.setBackgroundType(Style.BACKGROUND_IMAGE_TILE_BOTH);
s.setBorder(Border.createEmpty());
s.setBgImage(star);
s.setBgTransparency(0);

private Slider createStarRankSlider() {

Slider starRank = new Slider();

starRank.setEditable(true);
starRank.setMinValue(0);
starRank.setMaxValue(10);
Font fnt =
Font.createTrueTypeFont("native:MainLight", "native:MainLight").
derive(Display.getInstance().convertToPixels(5, true),
Font.STYLE_PLAIN);
Style s = new Style(0xffff33, 0, fnt, (byte)0);

Image fullStar = FontImage.createMaterial(FontImage.MATERIAL_STAR,

s).toImage();

248

The Components Of Codename One

s.setOpacity(100);

s.setFgColor(0);
Image emptyStar = FontImage.createMaterial(FontImage.MATERIAL_STAR,
s).toImage();

initStarRankStyle(starRank.getSliderEmptySelectedStyle(), emptyStar);
initStarRankStyle(starRank.getSliderEmptyUnselectedStyle(),
emptyStar);
initStarRankStyle(starRank.getSliderFullSelectedStyle(), fullStar);
initStarRankStyle(starRank.getSliderFullUnselectedStyle(), fullStar);
starRank.setPreferredSize(new Dimension(fullStar.getWidth() * 5,

fullStar.getHeight()));
}

return starRank;

private void showStarPickingForm() {

Form hi = new Form("Star Slider", new BoxLayout(BoxLayout.Y_AXIS));

hi.add(FlowLayout.encloseCenter(createStarRankSlider()));
hi.show();

Figure 5.35. Star Slider set to 5 (its between 0 - 10)

This slider goes all the way to 0 stars which is less common. You
can use a Label to represent the first star and have the slider work
between 0 - 8 values to provide 4 additional stars.

5.18.Table
75

Table is a composite component (but it isnt a lead component), this means it is a

76
subclass of Container . Its effectively built from multiple components.
77

Table is heavily based on the TableLayout class. Its important

to be familiar with that layout manager when working with Table .
75
76
77

https://www.codenameone.com/javadoc/com/codename1/ui/table/Table.html
https://www.codenameone.com/javadoc/com/codename1/ui/Container.html
https://www.codenameone.com/javadoc/com/codename1/ui/table/TableLayout.html

249

The Components Of Codename One

Here is a trivial sample of using the standard table component:
Form hi = new Form("Table", new BorderLayout());

TableModel model = new DefaultTableModel(new String[] {"Col 1", "Col

2", "Col 3"}, new Object[][] {
{"Row
{"Row
{"Row
{"Row
}) {

1",
2",
3",
4",

"Row
"Row
"Row
"Row

A",
B",
C",
D",

"Row
"Row
"Row
"Row

X"},
Y"},
Z"},
K"},

public boolean isCellEditable(int row, int col) {

};

return col != 0;

Table table = new Table(model);

hi.add(BorderLayout.CENTER, table);
hi.show();

250

The Components Of Codename One

Figure 5.36. Simple Table usage

In the sample above the title area and first column arent editable.
The other two columns are editable.
The more "interesting" capabilities of the Table class can be utilized via the
TableLayout . You can use the layout constraints (also exposed in the table class)
to create spanning and elaborate UIs.
E.g.:
Form hi = new Form("Table", new BorderLayout());

251

The Components Of Codename One

TableModel model = new DefaultTableModel(new String[] {"Col 1", "Col
2", "Col 3"}, new Object[][] {

{"Row 1", "Row A", "Row X"},

{"Row 2", "Row B can now stretch", null},
{"Row 3", "Row C", "Row Z"},
{"Row 4", "Row D", "Row K"},
}) {

public boolean isCellEditable(int row, int col) {

};

return col != 0;

Table table = new Table(model) {

@Override

protected TableLayout.Constraint createCellConstraint(Object

value, int row, int column) {

TableLayout.Constraint con =

row, column);

super.createCellConstraint(value,

if(row == 1 && column == 1) {

con.setHorizontalSpan(2);

}
con.setWidthPercentage(33);
}

return con;

};
hi.add(BorderLayout.CENTER, table);

252

The Components Of Codename One

Figure 5.37. Table with spanning & fixed widths to 33%

In order to customize the table cell behavior you can derive the Table to create a
"renderer like" widget, however unlike the list this component is "kept" and used as is.
This means you can bind listeners to this component and work with it as you would with
any other component in Codename One.
So lets fix the example above to include far more capabilities:
Table table = new Table(model) {
@Override

253

The Components Of Codename One

protected Component createCell(Object value, int row, int

column, boolean editable) {

Component cell;

if(row == 1 && column == 1) {

Picker p = new Picker();

p.setType(Display.PICKER_TYPE_STRINGS);
p.setStrings("Row B can now stretch", "This is a good
value", "So Is This", "Better than text field");
p.setSelectedString((String)value);
p.setUIID("TableCell");
p.addActionListener((e) -> getModel().setValueAt(row, column,
p.getSelectedString()));
cell = p;
} else {
}

cell = super.createCell(value, row, column, editable);

if(row > -1 && row % 2 == 0) {

// pinstripe effect

}
}

cell.getAllStyles().setBgColor(0xeeeeee);
cell.getAllStyles().setBgTransparency(255);

return cell;

@Override

protected TableLayout.Constraint createCellConstraint(Object

value, int row, int column) {

TableLayout.Constraint con =

row, column);

super.createCellConstraint(value,

if(row == 1 && column == 1) {

con.setHorizontalSpan(2);

}
con.setWidthPercentage(33);

};

return con;

The createCell method is invoked once per component but is similar

conceptually to the List renderer. Notice that it doesnt return a "rubber stamp"
though, it returns a full component.
We only apply the picker to one cell for simplicities sake.
We need to set the value of the component manually, this is crucial since the
Table doesnt "see" this.

254

The Components Of Codename One

We need to track the event and update the model in this case as the Table isnt
aware of the data change.
We set the "pinstripe" effect by coloring even rows. Notice that unlike renderers
we only need to apply the coloring once as the Components are stateful.

Figure 5.38. Table with customize cells using the pinstripe effect

255

The Components Of Codename One

Figure 5.39. Picker table cell during edit

To line wrap table cells we can just override the createCell method and return a
78
79
TextArea instead of a TextField since the TextArea defaults to the multi-line
behavior this should work seamlessly. E.g.:
Form hi = new Form("Table", new BorderLayout());

TableModel model = new DefaultTableModel(new String[] {"Col 1", "Col

2", "Col 3"}, new Object[][] {

78
79

https://www.codenameone.com/javadoc/com/codename1/ui/TextArea.html
https://www.codenameone.com/javadoc/com/codename1/ui/TextField.html

256

The Components Of Codename One

{"Row 1", "Row A", "Row X"},

{"Row 2", "Row B can now stretch very long line that should span
multiple rows as much as possible", "Row Y"},
{"Row 3", "Row C", "Row Z"},
{"Row 4", "Row D", "Row K"},
}) {

public boolean isCellEditable(int row, int col) {

};

return col != 0;

Table table = new Table(model) {

@Override

protected Component createCell(Object value, int row, int

column, boolean editable) {

TextArea ta = new TextArea((String)value);

ta.setUIID("TableCell");

return ta;

@Override

protected TableLayout.Constraint createCellConstraint(Object

value, int row, int column) {

TableLayout.Constraint con =

row, column);
con.setWidthPercentage(33);
}

super.createCellConstraint(value,

return con;

};
hi.add(BorderLayout.CENTER, table);
hi.show();

Notice that we dont really need to do anything else as binding to the

TextArea is builtin to the Table .
We must set the column width constraint when we want multi-line to
work. Otherwise the preferred size of the column might be too wide
and the remaining columns might not have space left.

257

The Components Of Codename One

Figure 5.40. Multiline table cell in portrait mode

258

The Components Of Codename One

Figure 5.41. Multiline table cell in landscape mode. Notice the cell
row count adapts seamlessly

5.19.Tree
80

Tree allows displaying hierarchical data such as folders and files in a collapsible/
expandable UI. Like the Table it is a composite component (but it isnt a lead
component). Like the Table it works in consort with a model to construct its user
interface on the fly but doesnt use a stateless renderer (as List does).
The data of the Tree arrives from a model model e.g. this:
class StringArrayTreeModel implements TreeModel {
String[][] arr = new String[][] {

};

{"Colors", "Letters", "Numbers"},

{"Red", "Green", "Blue"},
{"A", "B", "C"},
{"1", "2", "3"}

public Vector getChildren(Object parent) {

80

https://www.codenameone.com/javadoc/com/codename1/ui/tree/Tree.html

259

The Components Of Codename One

if(parent == null) {

Vector v = new Vector();

for(int iter = 0 ; iter < arr[0].length ; iter++) {

}
}

v.addElement(arr[0][iter]);

return v;

Vector v = new Vector();

for(int iter = 0 ; iter < arr[0].length ; iter++) {

if(parent == arr[0][iter]) {

if(arr.length > iter + 1 && arr[iter + 1] != null) {

for(int i = 0 ; i < arr[iter + 1].length ; i++) {

}
}

v.addElement(arr[iter + 1][i]);

return v;

public boolean isLeaf(Object node) {

Vector v = getChildren(node);

return v == null || v.size() == 0;

Tree dt = new Tree(new StringArrayTreeModel());

Will result in this:

260

The Components Of Codename One

Figure 5.42. Tree

Since Tree is hierarchy based we cant have a simple model like
we have for the Table as deep hierarchy is harder to represent
with arrays.
A more practical "real world" example would be working with XML data. We can use
something like this to show an XML Tree :
Form hi = new Form("XML Tree", new BorderLayout());

InputStream is = Display.getInstance().getResourceAsStream(getClass(), "/

build.xml");
try(Reader r = new InputStreamReader(is, "UTF-8")) {
Element e = new XMLParser().parse(r);

Tree xmlTree = new Tree(new XMLTreeModel(e)) {

@Override

protected String childToDisplayLabel(Object child) {

if(child instanceof Element) {
}
}

return ((Element)child).getTagName();

return child.toString();

};
hi.add(BorderLayout.CENTER, xmlTree);

} catch(IOException err) {
Log.e(err);

261

The Components Of Codename One

}

The try(Stream) syntax is a try with resources clogic that

implicitly closes the stream.

Figure 5.43. XML Tree

The model for the XML hierarchy is implemented as such:
class XMLTreeModel implements TreeModel {
private Element root;

public XMLTreeModel(Element e) {

262

The Components Of Codename One

root = e;

public Vector getChildren(Object parent) {

if(parent == null) {

Vector c = new Vector();

c.addElement(root);

return c;

Vector result = new Vector();

Element e = (Element)parent;

for(int iter = 0 ; iter < e.getNumChildren() ; iter++) {

}
}

result.addElement(e.getChildAt(iter));

return result;

public boolean isLeaf(Object node) {

Element e = (Element)node;

return e.getNumChildren() == 0;

5.20.ShareButton
ShareButton
of text.

81

is a button you can add into the UI to let a user share an image or block

The ShareButton uses a set of predefined share options on the simulator. On

Android & iOS the ShareButton is mapped to the OS native sharing functionality
and can share the image/text with the services configured on the device (e.g. Twitter,
Facebook etc.).
Sharing text is trivial but to share an image we need to save it to the
82
FileSystemStorage . Notice that saving to Storage wont work!
In the sample code below we take a screenshot which is saved to FileSystemStorage
for sharing:
81
82
83

https://www.codenameone.com/javadoc/com/codename1/components/ShareButton.html
https://www.codenameone.com/javadoc/com/codename1/io/FileSystemStorage.html
https://www.codenameone.com/javadoc/com/codename1/io/FileSystemStorage.html

263

83

The Components Of Codename One

Form hi = new Form("ShareButton");

ShareButton sb = new ShareButton();

sb.setText("Share Screenshot");
hi.add(sb);

Image screenshot = Image.createImage(hi.getWidth(), hi.getHeight());

hi.revalidate();
hi.setVisible(true);
hi.paintComponent(screenshot.getGraphics(), true);
String imageFile = FileSystemStorage.getInstance().getAppHomePath()
+ "screenshot.png";
try(OutputStream os =

FileSystemStorage.getInstance().openOutputStream(imageFile)) {
ImageIO.getImageIO().save(screenshot, os, ImageIO.FORMAT_PNG, 1);

} catch(IOException err) {
Log.e(err);

}
sb.setImageToShare(imageFile, "image/png");

264

The Components Of Codename One

Figure 5.44. The share button running on the simulator

ShareButton behaves very differently on the device

265

The Components Of Codename One

Figure 5.45. The share button running on the Android device and
screenshot sent into twitter
The ShareButton features some share service classes to allow
plugging in additional share services. However, this functionality is
only relevant to devices where native sharing isnt supported. So this
code isnt used on iOS/Android

5.21.Tabs
84

The Tabs
Container arranges components into groups within "tabbed"
containers. Tabs is a container type that allows leafing through its children using
labeled toggle buttons. The tabs can be placed in multiple different ways (top, bottom,
left or right) with the default being determined by the platform. This class also allows
84

https://www.codenameone.com/javadoc/com/codename1/ui/Tabs.html

266

The Components Of Codename One

swiping between components to leaf between said tabs (for this purpose the tabs
themselves can also be hidden).
Since Tabs are a Container its a common mistake to try and add a Tab using

the add method. That method wont work since a Tab can have both an Image and
text String associated with it.
Form hi = new Form("Tabs", new BorderLayout());
Tabs t = new Tabs();

Style s = UIManager.getInstance().getComponentStyle("Tab");
FontImage icon1 =
FontImage.createMaterial(FontImage.MATERIAL_QUESTION_ANSWER, s);
Container container1 = BoxLayout.encloseY(new Label("Label1"), new
Label("Label2"));
t.addTab("Tab1", icon1, container1);

t.addTab("Tab2", new SpanLabel("Some text directly in the tab"));

hi.add(BorderLayout.CENTER, t);

267

The Components Of Codename One

Figure 5.46. Simple usage of Tabs

A common usage for Tabs is the the swipe to proceed effect which is very common in
85
86
iOS applications. In the code below we use RadioButton and LayeredLayout with
hidden tabs to produce that effect:
Form hi = new Form("Swipe Tabs", new LayeredLayout());
Tabs t = new Tabs();
t.hideTabs();
85
86

https://www.codenameone.com/javadoc/com/codename1/ui/RadioButton.html
https://www.codenameone.com/javadoc/com/codename1/ui/layouts/LayeredLayout.html

268

The Components Of Codename One

Style s = UIManager.getInstance().getComponentStyle("Button");
FontImage radioEmptyImage =
FontImage.createMaterial(FontImage.MATERIAL_RADIO_BUTTON_UNCHECKED, s);

FontImage radioFullImage =
FontImage.createMaterial(FontImage.MATERIAL_RADIO_BUTTON_CHECKED, s);
((DefaultLookAndFeel)UIManager.getInstance().getLookAndFeel()).setRadioButtonImages(radi
radioEmptyImage, radioFullImage, radioEmptyImage);
Container container1 = BoxLayout.encloseY(new Label("Swipe the tab to see
more"),

new Label("You can put anything here"));

t.addTab("Tab1", container1);

t.addTab("Tab2", new SpanLabel("Some text directly in the tab"));

RadioButton firstTab = new RadioButton("");

RadioButton secondTab = new RadioButton("");

firstTab.setUIID("Container");
secondTab.setUIID("Container");

new ButtonGroup(firstTab, secondTab);

firstTab.setSelected(true);
Container tabsFlow = FlowLayout.encloseCenter(firstTab, secondTab);
hi.add(t);
hi.add(BorderLayout.south(tabsFlow));
t.addSelectionListener((i1, i2) -> {
switch(i2) {
case 0:

if(!firstTab.isSelected()) {
}

firstTab.setSelected(true);

break;

case 1:

if(!secondTab.isSelected()) {
}

});

secondTab.setSelected(true);

break;

269

The Components Of Codename One

Figure 5.47. Swipeable Tabs with an iOS carousel effect page 1

270

The Components Of Codename One

Figure 5.48. Swipeable Tabs with an iOS carousel effect page 2

Notice that we used setRadioButtonImages to explicitly set the
radio button images to the look we want for the carousel.

5.22.MediaManager & MediaPlayer

MediaPlayer is a peer component, understanding this is crucial
if your application depends on such a component. You can learn
about peer components and their issues here.

271

The Components Of Codename One

87

The MediaPlayer allows you to control video playback. To use the MediaPlayer
88
we need to first load the Media object from the MediaManager .
The MediaManager is the core class responsible for media interaction in Codename
One.

You should also check out the Capture

89

class for things that arent

covered by the MediaManager .

In the demo code below we use the gallery functionality to pick a video from the devices
video gallery.
final Form hi = new Form("MediaPlayer", new BorderLayout());
hi.setToolbar(new Toolbar());

Style s = UIManager.getInstance().getComponentStyle("Title");
FontImage icon =
FontImage.createMaterial(FontImage.MATERIAL_VIDEO_LIBRARY, s);
hi.getToolbar().addCommandToRightBar("", icon, (evt) -> {
Display.getInstance().openGallery((e) -> {
if(e != null && e.getSource() != null) {
String file = (String)e.getSource();
try {

Media video = MediaManager.createMedia(file, true);

hi.removeAll();

hi.add(BorderLayout.CENTER, new MediaPlayer(video));

hi.revalidate();

} catch(IOException err) {
Log.e(err);

}
}
}, Display.GALLERY_VIDEO);

});
hi.show();

87
88
89

https://www.codenameone.com/javadoc/com/codename1/components/MediaPlayer.html
https://www.codenameone.com/javadoc/com/codename1/media/MediaManager.html
https://www.codenameone.com/javadoc/com/codename1/capture/Capture.html

272

The Components Of Codename One

Figure 5.49. Video playback running on the simulator

273

The Components Of Codename One

274

The Components Of Codename One

Video playback in the simulator will only work with JavaFX enabled.
This is the default for Java 8 or newer so we recommend using that.

5.23.ImageViewer
90

The ImageViewer allows us to inspect, zoom and pan into an image. It also allows
swiping between images if you have a set of images (using an image list model).
The ImageViewer is a complex rich component designed for user
91
interaction. If you just want to display an image use Label if you
92
want the image to scale seamlessly use ScaleImageLabel .
You can use the ImageViewer as a tool to view a single image which allows you to
zoom in/out to that image as such:
Form hi = new Form("ImageViewer", new BorderLayout());
ImageViewer iv = new ImageViewer(duke);
hi.add(BorderLayout.CENTER, iv);

You can simulate pinch to zoom on the simulator by dragging the

right button away from the top left corner to zoom in and towards
the top left corner to zoom out. On Mac touchpads you can drag two
fingers to achieve that.

90
91
92

https://www.codenameone.com/javadoc/com/codename1/components/ImageViewer.html
https://www.codenameone.com/javadoc/com/codename1/ui/Label.html
https://www.codenameone.com/javadoc/com/codename1/components/ScaleImageLabel.html

275

The Components Of Codename One

Figure 5.51. ImageViewer as the demo loads with the image from
the default icon

276

The Components Of Codename One

Figure 5.52. ImageViewer zoomed in

We can work with a list of images to produce a swiping effect for the image viewer where
you can swipe from one image to the next and also zoom in/out on a specific image:
Form hi = new Form("ImageViewer", new BorderLayout());
Image
Image
Image
Image

red = Image.createImage(100, 100, 0xffff0000);

green = Image.createImage(100, 100, 0xff00ff00);
blue = Image.createImage(100, 100, 0xff0000ff);
gray = Image.createImage(100, 100, 0xffcccccc);

ImageViewer iv = new ImageViewer(red);

277

The Components Of Codename One

iv.setImageList(new DefaultListModel<>(red, green, blue, gray));
hi.add(BorderLayout.CENTER, iv);

Figure 5.53. An ImageViewer with multiple elements is

indistinguishable from a single ImageViewer with the exception of
swipe
Notice that we use a ListModel

93

93

to allow swiping between images.

https://www.codenameone.com/javadoc/com/codename1/ui/list/ListModel.html

278

The Components Of Codename One

EncodedImages arent always fully loaded and so when you
swipe if the images are really large you might see delays!
You can dynamically download images directly into the ImageViewer with a custom
list model like this:
Form hi = new Form("ImageViewer", new BorderLayout());

final EncodedImage placeholder = EncodedImage.createFromImage(

FontImage.createMaterial(FontImage.MATERIAL_SYNC, s).
scaled(300, 300), false);

class ImageList implements ListModel<Image> {

private int selection;

private String[] imageURLs = {

"http://awoiaf.westeros.org/images/thumb/9/93/

AGameOfThrones.jpg/300px-AGameOfThrones.jpg",
"http://awoiaf.westeros.org/images/thumb/3/39/
AClashOfKings.jpg/300px-AClashOfKings.jpg",
"http://awoiaf.westeros.org/images/thumb/2/24/
AStormOfSwords.jpg/300px-AStormOfSwords.jpg",
"http://awoiaf.westeros.org/images/thumb/a/a3/
AFeastForCrows.jpg/300px-AFeastForCrows.jpg",
"http://awoiaf.westeros.org/images/7/79/ADanceWithDragons.jpg"
};
private Image[] images;

private EventDispatcher listeners = new EventDispatcher();

public ImageList() {
}

this.images = new EncodedImage[imageURLs.length];

public Image getItemAt(final int index) {

if(images[index] == null) {

images[index] = placeholder;
Util.downloadUrlToStorageInBackground(imageURLs[index], "list"
+ index, (e) -> {
try {

images[index] =
EncodedImage.create(Storage.getInstance().createInputStream("list" +
index));
listeners.fireDataChangeEvent(index,
DataChangedListener.CHANGED);
} catch(IOException err) {
err.printStackTrace();

279

The Components Of Codename One

}
}

});

return images[index];

public int getSize() {

}

return imageURLs.length;

public int getSelectedIndex() {

}

return selection;

public void setSelectedIndex(int index) {

}

selection = index;

public void addDataChangedListener(DataChangedListener l) {

}

listeners.addListener(l);

public void removeDataChangedListener(DataChangedListener l) {

}

listeners.removeListener(l);

public void addSelectionListener(SelectionListener l) {

}

public void removeSelectionListener(SelectionListener l) {

}

public void addItem(Image item) {

}

public void removeItem(int index) {

};

ImageList imodel = new ImageList();

ImageViewer iv = new ImageViewer(imodel.getItemAt(0));
iv.setImageList(imodel);
hi.add(BorderLayout.CENTER, iv);

280

The Components Of Codename One

Figure 5.54. Dynamically fetching an image URL from the internet

94

This fetches the images in the URL asynchronously and fires a data change event when
the data arrives to automatically refresh the ImageViewer when that happens.

94

Image was fetched from http://awoiaf.westeros.org/index.php/Portal:Books

281

The Components Of Codename One

5.24.ScaleImageLabel & ScaleImageButton

ScaleImageLabel

95

& ScaleImageButton

96

allow us to position an image that will grow/

shrink to fit available space. In that sense they differ from Label & Button which keeps
the image at the same size.
The default UIID of ScaleImageLabel is Label, however the
default UIID of ScaleImageButton is ScaleImageButton. The
reasoning for the difference is that the Button UIID includes a
border and a lot of legacy.
You can use ScaleImageLabel / ScaleImageButton interchangeably. The only
major difference between these components is the buttons ability to handle click events/
focus.
Here is a simple example that also shows the difference between the scale to fill
and scale to fit modes:
TableLayout tl = new TableLayout(2, 2);

Form hi = new Form("ScaleImageButton/Label", tl);

Style s = UIManager.getInstance().getComponentStyle("Button");
Image icon = FontImage.createMaterial(FontImage.MATERIAL_WARNING, s);
ScaleImageLabel fillLabel = new ScaleImageLabel(icon);

fillLabel.setBackgroundType(Style.BACKGROUND_IMAGE_SCALED_FILL);
ScaleImageButton fillButton = new ScaleImageButton(icon);

fillButton.setBackgroundType(Style.BACKGROUND_IMAGE_SCALED_FILL);
hi.add(tl.createConstraint().widthPercentage(20), new
ScaleImageButton(icon)).

add(tl.createConstraint().widthPercentage(80), new

ScaleImageLabel(icon)).
add(fillLabel).
add(fillButton);
hi.show();

95
96

https://www.codenameone.com/javadoc/com/codename1/components/ScaleImageLabel.html
https://www.codenameone.com/javadoc/com/codename1/components/ScaleImageButton.html

282

The Components Of Codename One

Figure 5.55. ScaleImageLabel/Button, the top row includes scale to

fit versions (the default) whereas the bottom row includes the scale
to fill versions
When styling these components keep in mind that changing
attributes such as background behavior might cause an issue with
their functionality or might not work.

5.25.Toolbar
97

The Toolbar API provides deep customization of the title bar area with more flexibility
98
e.g. placing a TextField for search or buttons in arbitrary title area positions. The
Toolbar API replicates some of the native functionality available on Android/iOS and
integrates with features such as the side menu to provide very fine grained control over
the title area behavior.
The Toolbar needs to be installed into the Form in order for it to work. You can
setup the Toolbar in one of these three ways:
1. form.setToolbar(new Toolbar()); - allows you to activate the Toolbar
to a specific Form and not for the entire application
2. Toolbar.setGlobalToolbar(true); - enables the Toolbar for all the
forms in the app
3. Theme
constant
globalToobarBool
Toolbar.setGlobalToolbar(true);

this

is

equivalent

to

The basic functionality of the Toolbar includes the ability to add a command to the
following 4 places:
97
98

https://www.codenameone.com/javadoc/com/codename1/ui/Toolbar.html
https://www.codenameone.com/javadoc/com/codename1/ui/TextField.html

283

The Components Of Codename One

Left side of the title - addCommandToLeftBar
Right side of the title - addCommandToRightBar
Side menu bar (the drawer that opens when you click the icon on the top left or
swipe the screen from left to right) - addCommandToSideMenu
Overflow menu (the menu that opens when you tap the 3 vertical dots in the top
right corner) - addCommandToOverflowMenu
The code below provides a brief overview of these options:
Toolbar.setGlobalToolbar(true);
Form hi = new Form("Toolbar", new BoxLayout(BoxLayout.Y_AXIS));
hi.getToolbar().addCommandToLeftBar("Left", icon, (e) ->
Log.p("Clicked"));
hi.getToolbar().addCommandToRightBar("Right", icon, (e) ->

Log.p("Clicked"));
hi.getToolbar().addCommandToOverflowMenu("Overflow", icon, (e) ->
Log.p("Clicked"));
hi.getToolbar().addCommandToSideMenu("Sidemenu", icon, (e) ->
Log.p("Clicked"));
hi.show();

Figure 5.56. The Toolbar

284

The Components Of Codename One

Figure 5.57. The default sidemenu of the Toolbar

Figure 5.58. The overflow menu of the Toolbar

Normally you can just set a title with a String but if you would want the component to
be a text field or a multi line label you can use setTitleComponent(Component)
which allows you to install any component into the title area.
The code below demonstrates searching using custom code
however the Toolbar also has builtin support for search covered in
the next section
The customization of the title area allows for some pretty powerful UI effects e.g. the
code below allows searching dynamically within a set of entries and uses some very
neat tricks:
285

The Components Of Codename One

Toolbar.setGlobalToolbar(true);
Style s = UIManager.getInstance().getComponentStyle("Title");
Form hi = new Form("Toolbar", new BoxLayout(BoxLayout.Y_AXIS));
TextField searchField = new TextField("", "Toolbar Search");

searchField.getHintLabel().setUIID("Title");
searchField.setUIID("Title");
searchField.getAllStyles().setAlignment(Component.LEFT);
hi.getToolbar().setTitleComponent(searchField);
FontImage searchIcon = FontImage.createMaterial(FontImage.MATERIAL_SEARCH,
s);
searchField.addDataChangeListener((i1, i2) -> {
String t = searchField.getText();
if(t.length() < 1) {

for(Component cmp : hi.getContentPane()) {

cmp.setHidden(false);
cmp.setVisible(true);

} else {

t = t.toLowerCase();

for(Component cmp : hi.getContentPane()) {

String val = null;

if(cmp instanceof Label) {

val = ((Label)cmp).getText();

} else {

if(cmp instanceof TextArea) {

val = ((TextArea)cmp).getText();

} else {

val = (String)cmp.getPropertyValue("text");

boolean show = val != null && val.toLowerCase().indexOf(t) >

-1;

cmp.setHidden(!show);
cmp.setVisible(show);

}
hi.getContentPane().animateLayout(250);

});
hi.getToolbar().addCommandToRightBar("", searchIcon, (e) -> {
});

searchField.startEditingAsync();

hi.add("A Game of Thrones").

286

The Components Of Codename One

add("A Clash Of Kings").

add("A Storm Of Swords").

add("A Feast For Crows").
add("A Dance With Dragons").

add("The Winds of Winter").

add("A Dream of Spring");
hi.show();

We use a TextField the whole time and just style it to make it (and its hint) look
like a regular title. An alternative way is to replace the title component dynamically.
We use the DataChangeListener to update the search results as we type
them.
Hidden & Visible use the opposite flag values to say similar things (e.g. when
hidden is set to false you would want to set visible to true).
Visible indicates whether a component can be seen. It will still occupy the physical
space on the screen even when it isnt visible. Hidden will remove the space
occupied by the component from the screen, but some code might still try to paint
it. Normally, visible is redundant but we use it with hidden for good measure.
The search button is totally unnecessary here. We can just click the TextField !
However, that isnt intuitive to most users so we added the button to start editing.

287

The Components Of Codename One

Figure 5.59. Search field within the toolbar

288

The Components Of Codename One

Figure 5.60. Search field after typing a couple of letters

5.25.1.Search Mode
While you can implement search manually using the builtin search offers a simpler and
more uniform UI.

289

The Components Of Codename One

Figure 5.61. Builtin toolbar search functionality

You can customize the appearance of the search bar by using the UIIDs:
ToolbarSearch , TextFieldSearch & TextHintSearch .
In the sample below we fetch all the contacts from the device and enable search thru
them, notice it expects and image called duke.png which is really just the default
Codename One icon renamed and placed in the src folder:
Image duke = null;
try {

duke = Image.createImage("/duke.png");

} catch(IOException err) {
}

Log.e(err);

int fiveMM = Display.getInstance().convertToPixels(5);

final Image finalDuke = duke.scaledWidth(fiveMM);
Toolbar.setGlobalToolbar(true);

Form hi = new Form("Search", BoxLayout.y());

hi.add(new InfiniteProgress());

Display.getInstance().scheduleBackgroundTask(()-> {
// this will take a while...

Contact[] cnts = Display.getInstance().getAllContacts(true, true,

true, true, false, false);
Display.getInstance().callSerially(() -> {
hi.removeAll();
for(Contact c : cnts) {

MultiButton m = new MultiButton();

m.setTextLine1(c.getDisplayName());
m.setTextLine2(c.getPrimaryPhoneNumber());
Image pic = c.getPhoto();

290

The Components Of Codename One

if(pic != null) {

m.setIcon(fill(pic, finalDuke.getWidth(),
finalDuke.getHeight()));
} else {

m.setIcon(finalDuke);

}
hi.add(m);

});

});

}
hi.revalidate();

hi.getToolbar().addSearchCommand(e -> {
String text = (String)e.getSource();

if(text == null || text.length() == 0) {

// clear search

for(Component cmp : hi.getContentPane()) {

cmp.setHidden(false);
cmp.setVisible(true);

}
hi.getContentPane().animateLayout(150);

} else {

text = text.toLowerCase();

for(Component cmp : hi.getContentPane()) {

MultiButton mb = (MultiButton)cmp;
String line1 = mb.getTextLine1();
String line2 = mb.getTextLine2();
boolean show = line1 != null &&

line1.toLowerCase().indexOf(text) > -1 ||
line2 != null && line2.toLowerCase().indexOf(text) >
-1;
mb.setHidden(!show);
mb.setVisible(show);
}
}
}, 4);

hi.getContentPane().animateLayout(150);

hi.show();

5.25.2.Title Animations
Modern UIs often animate the title upon scrolling to balance the highly functional
smaller title advantage with the gorgeous large image based title. This is pretty easy to
do with the Toolbar API thru the Title animation API.
291

The Components Of Codename One

The code below shows off an attractive title based on a book by GRRM on top of text
99
that is scrollable. As the text is scrolled the title fades out.
Toolbar.setGlobalToolbar(true);
Form hi = new Form("Toolbar", new BoxLayout(BoxLayout.Y_AXIS));

EncodedImage placeholder =
EncodedImage.createFromImage(Image.createImage(hi.getWidth(),
hi.getWidth() / 5, 0xffff0000), true);
URLImage background = URLImage.createToStorage(placeholder, "400pxAGameOfThrones.jpg",
"http://awoiaf.westeros.org/images/thumb/9/93/
AGameOfThrones.jpg/400px-AGameOfThrones.jpg");
background.fetch();
Style stitle = hi.getToolbar().getTitleComponent().getUnselectedStyle();
stitle.setBgImage(background);
stitle.setBackgroundType(Style.BACKGROUND_IMAGE_SCALED_FILL);
stitle.setPaddingUnit(Style.UNIT_TYPE_DIPS, Style.UNIT_TYPE_DIPS,
Style.UNIT_TYPE_DIPS, Style.UNIT_TYPE_DIPS);
stitle.setPaddingTop(15);

SpanButton credit = new SpanButton("This excerpt is from A Wiki Of Ice And

Fire. Please check it out by clicking here!");
credit.addActionListener((e) -> Display.getInstance().execute("http://
awoiaf.westeros.org/index.php/A_Game_of_Thrones"));
hi.add(new SpanLabel("A Game of Thrones is the first of seven planned

novels in A Song of Ice and Fire, an epic fantasy series by American

author George R. R. Martin. It was first published on 6 August 1996.
The novel was nominated for the 1998 Nebula Award and the 1997 World
Fantasy Award,[1] and won the 1997 Locus Award.[2] The novella Blood of
the Dragon, comprising the Daenerys Targaryen chapters from the novel,
won the 1997 Hugo Award for Best Novella. ")).
add(new Label("Plot introduction", "Heading")).

add(new SpanLabel("A Game of Thrones is set in the Seven Kingdoms

of Westeros, a land reminiscent of Medieval Europe. In Westeros the

seasons last for years, sometimes decades, at a time.\n\n" +
"Fifteen years prior to the novel, the Seven Kingdoms were
torn apart by a civil war, known alternately as \"Robert's Rebellion\"
and the \"War of the Usurper.\" Prince Rhaegar Targaryen kidnapped Lyanna
Stark, arousing the ire of her family and of her betrothed, Lord Robert
Baratheon (the war's titular rebel). The Mad King, Aerys II Targaryen,
had Lyanna's father and eldest brother executed when they demanded her
safe return. Her second brother, Eddard, joined his boyhood friend Robert
Baratheon and Jon Arryn, with whom they had been fostered as children,
99

The text below is from A Wiki of Ice & Fire: http://awoiaf.westeros.org/index.php/A_Game_of_Thrones

292

The Components Of Codename One

in declaring war against the ruling Targaryen dynasty, securing the

allegiances of House Tully and House Arryn through a network of dynastic

marriages (Lord Eddard to Catelyn Tully and Lord Arryn to Lysa Tully).
The powerful House Tyrell continued to support the King, but House

Lannister and House Martell both stalled due to insults against their
houses by the Targaryens. The civil war climaxed with the Battle of the
Trident, when Prince Rhaegar was killed in battle by Robert Baratheon.
The Lannisters finally agreed to support King Aerys, but then brutally...
")).
add(credit);
ComponentAnimation title =
hi.getToolbar().getTitleComponent().createStyleAnimation("Title", 200);
hi.getAnimationManager().onTitleScrollAnimation(title);
hi.show();

293

The Components Of Codename One

Figure 5.62. The Toolbar starts with the large URLImage fetched
from the web

294

The Components Of Codename One

Figure 5.63. As we scroll down the image fades and the title shrinks
in size returning to the default UIID look

295

The Components Of Codename One

Figure 5.64. As scrolling continues the title reaches standard size

Almost all of the code above just creates the "look" of the application. The key piece
of code above is this:
ComponentAnimation title =
hi.getToolbar().getTitleComponent().createStyleAnimation("Title", 200);
hi.getAnimationManager().onTitleScrollAnimation(title);

In the first line we create a style animation that will translate the style from the current
settings to the destination UIID (the first argument) within 200 pixels of scrolling. We
then bind this animation to the title scrolling animation event.
296

The Components Of Codename One

5.26.BrowserComponent & WebBrowser

BrowserComponent is a peer component, understanding this is

crucial if your application depends on such a component. You can

learn about peer components and their issues here.
100

The WebBrowser
component shows the native device web browser when supported
101
by the device and the HTMLComponent
when the web browser isnt supported
on the given device. If you only intend to target smartphones you should use the
102
BrowserComponent
directly instead of the WebBrowser .
The BrowserComponent can point at an arbitrary URL to load it:
Form hi = new Form("Browser", new BorderLayout());
BrowserComponent browser = new BrowserComponent();
browser.setURL("https://www.codenameone.com/");
hi.add(BorderLayout.CENTER, browser);

100
101
102

https://www.codenameone.com/javadoc/com/codename1/components/WebBrowser.html
https://www.codenameone.com/javadoc/com/codename1/ui/html/HTMLComponent.html
https://www.codenameone.com/javadoc/com/codename1/ui/BrowserComponent.html

297

The Components Of Codename One

Figure 5.65. Browser Component showing the Codename One

website on the simulator
The scrollbars only appear in the simulator, device versions of the
browser component act differently and support touch scrolling.
A BrowserComponent should be in the center of a BorderLayout.
Otherwise its preferred size might be zero before the HTML finishes
loading/layout in the native layer and layout might be incorrect as a
result.

298

The Components Of Codename One

You can use WebBrowser and BrowserComponent interchangeably for most basic
usage. However, if you need access to JavaScript or native browser functionality then
there is really no use in going thru the WebBrowser abstraction.
The BrowserComponent has full support for executing local web pages from within
the jar. The basic support uses the jar:/// URL as such:
BrowserComponent wb = new BrowserComponent();
wb.setURL("jar:///Page.html");

On Android a native indicator might show up when the

web page is loading. This can be disabled using the
Display.getInstance().setProperty("WebLoadingHidden",
"true"); call. You only need to invoke this once.

5.26.1.BrowserComponent Hierarchy
When Codename One packages applications into native apps it hides a lot of details
to make the process simpler. One of the things hidden is the fact that we arent dealing
with a JAR anymore, so getResource / getResourceAsStream are problematic
Both of these APIs support hierarchies and a concept of package relativity both of
which might not be supported on all OSs.
103

Codename One has its own getResourceAsSteam in the Display

works just fine, but it requires that all files be in the src root directory.

class and that

Thats why we recommend that you place files inside res files. A
resource file allows you to add arbitrary data files and you can have
as many resource files as you need.
For web developers this isnt enough since hierarchies are used often to represent the
various dependencies, this means that many links & references are relative. To work
with such hierarchies just place all of your resources in a hierarchy under the html
package in the project root. The build server will tar the entire content of that package
and add an html.tar file into the native package. This tar is seamlessly extracted
on the device when you actually need the resources and only with new application
versions (not on every launch). So assuming the resources are under the html root
package they can be displayed with code like this:
103

https://www.codenameone.com/javadoc/com/codename1/ui/Display.html

299

The Components Of Codename One

try {

browserComponent.setURLHierarchy("/htmlFile.html");

} catch(IOException err) {
}

...

Notice that the path is relative to the html directory and starts with / but inside the
HTML files you should use relative (not absolute) paths.
Also notice that an IOException can be thrown due to the process of untarring. Its
unlikely to happen but is entirely possible.

5.26.2.NavigationCallback
104

At the core of the BrowserComponent we have the BrowserNavigationCallback

.
It might not seem like the most important interface within the browser but it is the "glue"
that allows the JavaScript code to communicate back into the Java layer.
You
can
bind
a
BrowserNavigationCallback
by
invoking
setBrowserNavigationCallback on the BrowserComponent . At that point
with every navigation within the browser the callback will get invoked.
The
shouldNavigate
method
from
the
BrowserNavigationCallback is invoked in a native thread and
NOT ON THE EDT!
It is crucial that this method returns immediately and that it wont do
any changes on the UI.
The shouldNavigate indicates to the native code whether navigation should
proceed or not. E.g. if a user clicks a specific link we might choose to do something
in the Java code so we can just return false and block the navigation. We can invoke
105
callSerially
to do the actual task in the Java side.
Form hi = new Form("BrowserComponent", new BorderLayout());
BrowserComponent bc = new BrowserComponent();
bc.setPage( "<html lang=\"en\">\n" +
"
<head>\n" +
104
105

https://www.codenameone.com/javadoc/com/codename1/ui/events/BrowserNavigationCallback.html
https://www.codenameone.com/javadoc/com/codename1/ui/Display.html#callSerially-

java.lang.Runnable-

300

The Components Of Codename One

"

<meta charset=\"utf-8\">\n" +

"
"
"

<script>\n" +
function fnc(message) {\n" +
document.write(message);\n" +

"
};\n" +
"
</script>\n" +
"
</head>\n" +
"
<body >\n" +
"
<p><a href=\"http://click\">Demo</a></p>\n" +
"
</body>\n" +
"</html>", null);
hi.add(BorderLayout.CENTER, bc);
bc.setBrowserNavigationCallback((url) -> {
if(url.startsWith("http://click")) {

Display.getInstance().callSerially(() -> bc.execute("fnc('<p>You

clicked!</p>')"));
}
});

return false;

return true;

Figure 5.66. Before the link is clicked for the "shouldNavigate" call

Figure 5.67. After the link is clicked for the "shouldNavigate" call
The JavaScript Bridge is implemented
BrowserNavigationCallback .

301

on

top

of

the

The Components Of Codename One

5.26.3.JavaScript
The JavaScript bridge is sometimes confused with the JavaScript
Port. The JavaScript bridge allows us to communicate with
JavaScript from Java (and visa versa). The JavaScript port allows
you to compile the Codename One application into a JavaScript
application that runs in a standard web browser without code
changes (think GWT without source changes and with thread
support).+ We discuss the JavaScript port further later in the guide.
BrowserComponent can communicate with the HTML code using JavaScript calls.
E.g. we can create HTML like this:
Form hi = new Form("BrowserComponent", new BorderLayout());
BrowserComponent bc = new BrowserComponent();

bc.setPage( "<html lang=\"en\">\n" +

"
<head>\n" +
"
<meta charset=\"utf-8\">\n" +
"
<script>\n" +
"
function fnc(message) {\n" +
"
document.write(message);\n" +
"
};\n" +
"
</script>\n" +
"
</head>\n" +
"
<body >\n" +
"
<p>Demo</p>\n" +
"
</body>\n" +
"</html>", null);
TextField tf = new TextField();

hi.add(BorderLayout.CENTER, bc).
add(BorderLayout.SOUTH, tf);
bc.addWebEventListener("onLoad", (e) -> bc.execute("fnc('<p>Hello World</
p>')"));
tf.addActionListener((e) -> bc.execute("fnc('<p>" + tf.getText() +"</
p>')"));
hi.show();

302

The Components Of Codename One

Figure 5.68. JavaScript code was invoked to append text into the
browser image above
Notice that opening an alert in an embedded native browser might
not work
We use the execute method above to execute custom JavaScript code. We also
have an executeAndReturnString method that allows us to receive a response
value from the JavaScript side.
Coupled with shouldNavigate we can effectively do everything which is exactly
what the JavaScript Bridge tries to do.

The JavaScript Bridge

While its possible to just build everything on top of execute and shouldNavigate ,
both of these methods have their limits. That is why we introduced the javascript
package, it allows you to communicate with JavaScript using intuitive code/syntax.
106

The JavascriptContext
class lays the foundation by enabling you to call JavaScript
code directly from Java. It provides automatic type conversion between Java and
JavaScript types as follows:

106

https://www.codenameone.com/javadoc/com/codename1/javascript/JavascriptContext.html

303

The Components Of Codename One

Table 5.1. Java to JavaScript

Java Type

Javascript Type

String

String

Double/Integer/Float/Long

Number

Boolean

Boolean

JSObject

Object

null

null

Other

Not Allowed

Table 5.2. JavaScript to Java

Javascript Type

Java Type

String

String

Number

Double

Boolean

Boolean

Object

JSObject

Function

JSObject

Array

JSObject

null

null

undefined

null
This conversion table is more verbose than necessary, since
JavaScript functions and arrays are, in fact Objects themselves, so
those rows are redundant. All JavaScript objects are converted to
JSObject

107

We can access JavaScript variables easily from the context by using code like this:
Form hi = new Form("BrowserComponent", new BorderLayout());
BrowserComponent bc = new BrowserComponent();

bc.setPage( "<html lang=\"en\">\n" +

"
<head>\n" +
"
<meta charset=\"utf-8\">\n" +
"
</head>\n" +
107

https://www.codenameone.com/javadoc/com/codename1/javascript/JSObject.html

304

The Components Of Codename One

"

<body >\n" +

"
<p>This will appear twice...</p>\n" +
"
</body>\n" +
"</html>", null);

hi.add(BorderLayout.CENTER, bc);
bc.addWebEventListener("onLoad", (e) -> {

// Create a Javascript context for this BrowserComponent

JavascriptContext ctx = new JavascriptContext(bc);

String pageContent = (String)ctx.get("document.body.innerHTML");

hi.add(BorderLayout.SOUTH, pageContent);
hi.revalidate();

});
hi.show();

Figure 5.69. The contents was copied from the DOM and placed in
the south position of the form
Notice that when you work with numeric values or anything related to the types
mentioned above your code must be aware of the typing. E.g. in this case the type is
Double and not String :
Double outerWidth = (Double)ctx.get("window.outerWidth");

You can also query the context for objects and modify their value e.g.
Form hi = new Form("BrowserComponent", new BorderLayout());

305

The Components Of Codename One

BrowserComponent bc = new BrowserComponent();

bc.setPage( "<html lang=\"en\">\n" +

"
<head>\n" +
"
<meta charset=\"utf-8\">\n" +
"
</head>\n" +
"
<body >\n" +
"
<p>Please Wait...</p>\n" +
"
</body>\n" +
"</html>", null);
hi.add(BorderLayout.CENTER, bc);
bc.addWebEventListener("onLoad", (e) -> {

// Create a Javascript context for this BrowserComponent

JavascriptContext ctx = new JavascriptContext(bc);

});

JSObject jo = (JSObject)ctx.get("window");
jo.set("location", "https://www.codenameone.com/");

This code effectively navigates to the Codename One home page by fetching
the DOMs window object and setting its location property to https://
www.codenameone.com/.

5.26.4.Cordova/PhoneGap Integration
PhoneGap was one of the first web app packager tools in the market. Its a tool that
is effectively a browser component within a native wrapper coupled with native access
APIs. Cordova is the open source extension of this popular project.
Codename One supports embedding PhoneGap/Cordova applications directly
into Codename One applications. This is relatively easy to do with the
BrowserComponent and JavaScript integration. The main aspect that this integration
requires is support for Cordova plugins & its JavaScript APIs.

The effort to integrate Cordova/PhoneGap support into Codename One is handled

108
within an open source github project here
. The chief benefits of picking Codename
One rather than using Cordova directly are:
Build Cloud
Better Native Code Support
Better Protection Of IP
108

https://github.com/codenameone/CN1Cordova

306

The Components Of Codename One

IDE Integration Java - JavaScript - HTML
Easy, Doesnt Require A Mac, Automates Certificates/Signing
Migration To Java
This is discussed further in the original announcement

109

5.27.AutoCompleteTextField
110

The AutoCompleteTextField
allows us to write text into a text field and select a
completion entry from the list in a similar way to a search engine.
111

This is really easy to incorporate into your code, just replace your usage of TextField
with AutoCompleteTextField and define the data that the autocomplete should
work from. There is a default implementation that accepts a String array or a
112
ListModel
for completion strings, this can work well for a "small" set of thousands
(or tens of thousands) of entries.
E.g. This is a trivial use case that can work well for smaller sample sizes:
Form hi = new Form("Auto Complete", new BoxLayout(BoxLayout.Y_AXIS));
AutoCompleteTextField ac = new

AutoCompleteTextField("Short", "Shock", "Sholder", "Shrek");

ac.setMinimumElementsShownInPopup(5);
hi.add(ac);

109
https://www.codenameone.com/blog/phonegap-cordova-compatibility-for-codename-one.html
110
https://www.codenameone.com/javadoc/com/codename1/ui/AutoCompleteTextField.html
111
https://www.codenameone.com/javadoc/com/codename1/ui/TextField.html
112
https://www.codenameone.com/javadoc/com/codename1/ui/list/ListModel.html

307

The Components Of Codename One

Figure 5.70. Autocomplete Text Field

However, if you wish to query a database or a web service you will need to derive the
class and perform more advanced filtering by overriding the filter method:
public void showForm() {

final DefaultListModel<String> options = new DefaultListModel<>();

AutoCompleteTextField ac = new AutoCompleteTextField(options) {
@Override

protected boolean filter(String text) {

if(text.length() == 0) {
}

return false;

String[] l = searchLocations(text);
if(l == null || l.length == 0) {
}

return false;

options.removeAll();
for(String s : l) {
}
}

options.addItem(s);

return true;

308

The Components Of Codename One

};

ac.setMinimumElementsShownInPopup(5);
hi.add(ac);

hi.add(new SpanLabel("This demo requires a valid google API key to be

set below "

+ "you can get this key for the webservice (not the native key)
by following the instructions here: "
+ "https://developers.google.com/places/web-service/get-apikey"));
hi.add(apiKey);
hi.getToolbar().addCommandToRightBar("Get Key", null, e ->
Display.getInstance().execute("https://developers.google.com/places/webservice/get-api-key"));
hi.show();
}
TextField apiKey = new TextField();
String[] searchLocations(String text) {
try {

if(text.length() > 0) {

ConnectionRequest r = new ConnectionRequest();

r.setPost(false);
r.setUrl("https://maps.googleapis.com/maps/api/place/
autocomplete/json");
r.addArgument("key", apiKey.getText());
r.addArgument("input", text);
NetworkManager.getInstance().addToQueueAndWait(r);
Map<String,Object> result = new

JSONParser().parseJSON(new InputStreamReader(new

ByteArrayInputStream(r.getResponseData()), "UTF-8"));
String[] res = Result.fromContent(result).getAsStringArray("//
description");
}

return res;

} catch(Exception err) {
}
}

Log.e(err);

return null;

309

The Components Of Codename One

Figure 5.71. Autocomplete Text Field with a webservice

5.28.Picker
113

Picker
occupies the limbo between native widget and lightweight widget. Picker is
more like TextField / TextArea in the sense that its a Codename One widget that
calls the native code only during editing.
The reasoning for this is the highly native UX and functionality related to this widget
type which should be quite obvious from the screenshots below.
At this time there are 4 types of pickers:
Time
Date & Time
Date
Strings
If a platform doesnt support native pickers an internal fallback implementation is used.
This is the implementation we always use in the simulator so assume different behavior
when building for the device.
While Android supports Date, Time native pickers it doesnt support
the Date & Time native picker UX and will fallback in that case.
113

https://www.codenameone.com/javadoc/com/codename1/ui/spinner/Picker.html

310

The Components Of Codename One

The sample below includes al picker types:
Form hi = new Form("Picker", new BoxLayout(BoxLayout.Y_AXIS));
Picker datePicker = new Picker();

datePicker.setType(Display.PICKER_TYPE_DATE);
Picker dateTimePicker = new Picker();

dateTimePicker.setType(Display.PICKER_TYPE_DATE_AND_TIME);
Picker timePicker = new Picker();

timePicker.setType(Display.PICKER_TYPE_TIME);
Picker stringPicker = new Picker();

stringPicker.setType(Display.PICKER_TYPE_STRINGS);
datePicker.setDate(new Date());

dateTimePicker.setDate(new Date());

timePicker.setTime(10 * 60); // 10:00AM = Minutes since midnight

stringPicker.setStrings("A Game of Thrones", "A Clash Of Kings", "A Storm

Of Swords", "A Feast For Crows",
"A Dance With Dragons", "The Winds of Winter", "A Dream of
Spring");
stringPicker.setSelectedString("A Game of Thrones");
hi.add(datePicker).add(dateTimePicker).add(timePicker).add(stringPicker);
hi.show();

Figure 5.72. The various picker components

311

The Components Of Codename One

Figure 5.73. The date & time picker on the simulator

312

The Components Of Codename One

Figure 5.74. The date picker component on the Android device

313

The Components Of Codename One

Figure 5.75. Date & time picker on Android. Notice it didnt use a
builtin widget since there is none

314

The Components Of Codename One

Figure 5.76. String picker on the native Android device

315

The Components Of Codename One

Figure 5.77. Time picker on the Android device

The text displayed by the picker on selection is generated automatically by the
updateValue() method. You can override it to display a custom formatted value
and call setText(String) with the correct display string.
A common use case is to format date values based on a specific appearance
and Picker has builtin support for a custom display formatter. Just use the
setFormatter(SimpleDateFormat) method and set the appearance for the field.

316

The Components Of Codename One

5.29.SwipeableContainer
The SwipeableContainer

114

allows us to place a component such as a MultiButton

115

on top of additional "options" that can be exposed by swiping the component to the side.
This swipe gesture is commonly used in touch interfaces to expose features such as
delete, edit etc. Its trivial to use this component by just determining the components
placed on top and bottom (the revealed component).
SwipeableContainer swip = new SwipeableContainer(bottom, top);

We can combine some of the demos above including the Slider stars demo to rank
GRRMs books in an interactive way:
Form hi = new Form("Swipe", new BoxLayout(BoxLayout.Y_AXIS));
hi.add(createRankWidget("A Game of Thrones", "1996")).
add(createRankWidget("A Clash Of Kings", "1998")).
add(createRankWidget("A Storm Of Swords", "2000")).
add(createRankWidget("A Feast For Crows", "2005")).
add(createRankWidget("A Dance With Dragons", "2011")).
add(createRankWidget("The Winds of Winter", "TBD")).
add(createRankWidget("A Dream of Spring", "TBD"));
hi.show();

public SwipeableContainer createRankWidget(String title, String year) {

MultiButton button = new MultiButton(title);
button.setTextLine2(year);
return new

SwipeableContainer(FlowLayout.encloseCenterMiddle(createStarRankSlider()),
button);

114
115

https://www.codenameone.com/javadoc/com/codename1/ui/SwipeableContainer.html
https://www.codenameone.com/javadoc/com/codename1/components/MultiButton.html

317

The Components Of Codename One

Figure 5.78. SwipableContainer showing a common use case of

ranking on swipe

5.30.EmbeddedContainer
116

EmbeddedContainer
solves a problem that exists only within the GUI builder and
the class makes no sense outside of the context of the GUI builder. The necessity
for EmbeddedContainer came about due to iPhone inspired designs that relied on

116

https://www.codenameone.com/javadoc/com/codename1/ui/util/EmbeddedContainer.html

318

The Components Of Codename One

tabs (iPhone style tabs at the bottom of the screen) where different features of the
application are within a different tab.
This didnt mesh well with the GUI builder navigation logic and so we needed to rethink
some of it. We wanted to reuse GUI as much as possible while still enjoying the
advantage of navigation being completely managed for me.
Android does this with Activities and the iPhone itself has a view controller, both
approaches are problematic for Codename One. The problem is that you have what is
effectively two incompatible hierarchies to mix and match.
The Component/Container hierarchy is powerful enough to represent such a UI but
117
we needed a "marker" to indicate to the UIBuilder
where a "root" component exists
so navigation occurs only within the given "root". Here EmbeddedContainer comes
into play, its a simple container that can only contain another GUI from the GUI builder.
Nothing else. So we can place it in any form of UI and effectively have the UI change
appropriately and navigation would default to "sensible values".
Navigation replaces the content of the embedded container; it finds the embedded
container based on the component that broadcast the event. If you want to navigate
manually just use the showContainer() method which accepts a component, you can
give any component that is under the EmbeddedContainer you want to replace and
Codename One will be smart enough to replace only that component.
The nice part about using the EmbeddedContainer is that the resulting UI can be
very easily refactored to provide a more traditional form based UI without duplicating
effort and can be easily adapted to a more tablet oriented UI (with a side bar) again
without much effort.

5.31.MapComponent
The MapComponent uses a somewhat outdated tiling API which
is not as rich as modern native maps. We recommend using
118
the GoogleMaps Native cn1lib
to integrate native mapping
functionality into the Codename One app.
The MapComponent
navigatable map.
117
118
119

119

uses the OpenStreetMap webservice by default to display a

https://www.codenameone.com/javadoc/com/codename1/ui/util/UIBuilder.html
https://github.com/codenameone/codenameone-google-maps/
https://www.codenameone.com/javadoc/com/codename1/maps/MapComponent.html

319

The Components Of Codename One

The code was contributed by Roman Kamyk and was originally used for a LWUIT
application.

Figure 5.79. Map Component

The screenshot above was produced using the following code:
Form map = new Form("Map");

map.setLayout(new BorderLayout());
map.setScrollable(false);

final MapComponent mc = new MapComponent();

try {

//get the current location from the Location API

Location loc =
LocationManager.getLocationManager().getCurrentLocation();
Coord lastLocation = new Coord(loc.getLatitude(), loc.getLongtitude());
Image i = Image.createImage("/blue_pin.png");
PointsLayer pl = new PointsLayer();
pl.setPointIcon(i);

PointLayer p = new PointLayer(lastLocation, "You Are Here", i);

p.setDisplayName(true);

320

The Components Of Codename One

pl.addPoint(p);

mc.addLayer(pl);

} catch (IOException ex) {

ex.printStackTrace();

}
mc.zoomToLayers();

map.addComponent(BorderLayout.CENTER, mc);
map.addCommand(new BackCommand());

map.setBackCommand(new BackCommand());
map.show();

120

The example below shows how to integrate the MapComponent

with the Google
121
122
Location
API. make sure to obtain your secret api key from the Google Location
data API at: https://developers.google.com/maps/documentation/places/

Figure 5.80. MapComponent with Google Location API

final Form map = new Form("Map");
120
121
122

https://www.codenameone.com/javadoc/com/codename1/maps/MapComponent.html
https://www.codenameone.com/javadoc/com/codename1/location/Location.html
https://www.codenameone.com/javadoc/com/codename1/location/Location.html

321

The Components Of Codename One

map.setLayout(new BorderLayout());
map.setScrollable(false);

final MapComponent mc = new MapComponent();

Location loc =

LocationManager.getLocationManager().getCurrentLocation();
//use the code from above to show you on the map
putMeOnMap(mc);
map.addComponent(BorderLayout.CENTER, mc);
map.addCommand(new BackCommand());

map.setBackCommand(new BackCommand());
ConnectionRequest req = new ConnectionRequest() {

IOException {

protected void readResponse(InputStream input) throws

JSONParser p = new JSONParser();

Hashtable h = p.parse(new InputStreamReader(input));

// "status" : "REQUEST_DENIED"

String response = (String)h.get("status");

if(response.equals("REQUEST_DENIED")){

System.out.println("make sure to obtain a key from

"

+ "https://developers.google.com/maps/

documentation/places/");
progress.dispose();
Dialog.show("Info", "make sure to obtain an
application key from "
+ "google places api's"
, "Ok", null);
}

return;

final Vector v = (Vector) h.get("results");

Image im = Image.createImage("/red_pin.png");
PointsLayer pl = new PointsLayer();
pl.setPointIcon(im);

pl.addActionListener(new ActionListener() {
public void actionPerformed(ActionEvent evt) {

PointLayer p = (PointLayer) evt.getSource();

System.out.println("pressed " + p);

null);

Dialog.show("Details", "" + p.getName(), "Ok",

}

322

The Components Of Codename One

});
for (int i = 0; i < v.size(); i++) {

Hashtable entry = (Hashtable) v.elementAt(i);

Hashtable geo = (Hashtable) entry.get("geometry");
Hashtable loc = (Hashtable) geo.get("location");
Double lat = (Double) loc.get("lat");
Double lng = (Double) loc.get("lng");
PointLayer point = new PointLayer(new

Coord(lat.doubleValue(), lng.doubleValue()),
(String) entry.get("name"), null);
pl.addPoint(point);
}
progress.dispose();
mc.addLayer(pl);
map.show();
mc.zoomToLayers();
}

};
req.setUrl("https://maps.googleapis.com/maps/api/place/search/

json");

req.setPost(false);
req.addArgument("location", "" + loc.getLatitude() + "," +
loc.getLongtitude());
req.addArgument("radius", "500");
req.addArgument("types", "food");
req.addArgument("sensor", "false");
//get your own key from https://developers.google.com/maps/

documentation/places/

//and replace it here.

String key = "yourAPIKey";

req.addArgument("key", key);

NetworkManager.getInstance().addToQueue(req);

catch (IOException ex) {

ex.printStackTrace();

323

The Components Of Codename One

5.32.Chart Component
The charts package enables Codename One developers to add charts and

visualizations to their apps without having to include external libraries or embedding

web views. We also wanted to harness the new features in the graphics pipeline to
maximize performance.

5.32.1.Device Support
Since the charts package makes use of 2D transformations and shapes, it requires
some of the graphics features that are not yet available on all platforms. Currently the
following platforms are supported:
1. Simulator
2. Android
3. iOS

5.32.2.Features
1. Built-in support for many common types of charts including bar charts, line
charts, stacked charts, scatter charts, pie charts and more.
2. Pinch Zoom - The ChartComponent
support.

123

3. Panning Support - The ChartComponent

panning.

class includes optional pinch zoom

124

class includes optional support for

5.32.3.Chart Types
The com.codename1.charts package includes models and renderers for many
different types of charts. It is also extensible so that you can add your own chart types
if required. The following screen shots demonstrate a small sampling of the types of
charts that can be created.

123
124

https://www.codenameone.com/javadoc/com/codename1/charts/ChartComponent.html
https://www.codenameone.com/javadoc/com/codename1/charts/ChartComponent.html

324

The Components Of Codename One

Figure 5.81. Line Charts

Figure 5.82. Cubic Line Charts

325

The Components Of Codename One

Figure 5.83. Bar Charts

Figure 5.84. Stacked Bar Charts

326

The Components Of Codename One

Figure 5.85. Range Bar Charts

Figure 5.86. Pie Charts

327

The Components Of Codename One

Figure 5.87. Doughnut Charts

Figure 5.88. Scatter Charts

328

The Components Of Codename One

Figure 5.89. Dial Charts

Figure 5.90. Combined Charts

329

The Components Of Codename One

Figure 5.91. Bubble Charts

Figure 5.92. Time Charts

125

The above screenshots were taken from the ChartsDemo app

.
You can start playing with this app by checking it out from our git
repository.

125

https://github.com/codenameone/codenameone-demos/tree/master/ChartsDemo

330

The Components Of Codename One

5.32.4.How to Create A Chart

Adding a chart to your app involves four steps:
1. Build the model. You can construct a model (aka data set) for the chart using one
of the existing model classes in the com.codename1.charts.models package.
Essentially, this is just where you add the data that you want to display.
2. Set up a renderer. You can create a renderer for your chart using one of the existing
renderer classes in the com.codename1.charts.renderers package. The
renderer allows you to specify how the chart should look. E.g. the colors, fonts,
styles, to use.
3. Create the Chart View. Use one of the existing view classes in the
com.codename1.charts.views package.
126

4. Create a ChartComponent . In order to add your chart to the UI, you need to
127
wrap it in a ChartComponent
object.
128

You can check out the ChartsDemo

app for specific examples, but here is a high
level view of some code that creates a Pie Chart.
/**
* Creates a renderer for the specified colors.
*/
private DefaultRenderer buildCategoryRenderer(int[] colors) {
DefaultRenderer renderer = new DefaultRenderer();
renderer.setLabelsTextSize(15);
renderer.setLegendTextSize(15);

renderer.setMargins(new int[]{20, 30, 15, 0});

for (int color : colors) {

SimpleSeriesRenderer r = new SimpleSeriesRenderer();

}
}

r.setColor(color);
renderer.addSeriesRenderer(r);

return renderer;

/**
* Builds a category series using the provided values.
*
126
127
128

https://www.codenameone.com/javadoc/com/codename1/charts/ChartComponent.html
https://www.codenameone.com/javadoc/com/codename1/charts/ChartComponent.html
https://github.com/codenameone/codenameone-demos/tree/master/ChartsDemo

331

The Components Of Codename One

* @param titles the series titles
* @param values the values
* @return the category series
*/
protected CategorySeries buildCategoryDataset(String title, double[]
values) {

CategorySeries series = new CategorySeries(title);

int k = 0;

for (double value : values) {

}

series.add("Project " + ++k, value);

return series;

public Form createPieChartForm() {

// Generate the values

double[] values = new double[]{12, 14, 11, 10, 19};

// Set up the renderer

int[] colors = new int[]{ColorUtil.BLUE, ColorUtil.GREEN,

ColorUtil.MAGENTA, ColorUtil.YELLOW, ColorUtil.CYAN};

DefaultRenderer renderer = buildCategoryRenderer(colors);
renderer.setZoomButtonsVisible(true);
renderer.setZoomEnabled(true);
renderer.setChartTitleTextSize(20);
renderer.setDisplayValues(true);
renderer.setShowLabels(true);
SimpleSeriesRenderer r = renderer.getSeriesRendererAt(0);
r.setGradientEnabled(true);
r.setGradientStart(0, ColorUtil.BLUE);
r.setGradientStop(0, ColorUtil.GREEN);
r.setHighlighted(true);
// Create the chart ... pass the values and renderer to the chart

object.

PieChart chart = new PieChart(buildCategoryDataset("Project budget",

values), renderer);

// Wrap the chart in a Component so we can add it to a form

ChartComponent c = new ChartComponent(chart);
// Create a form and show it.
Form f = new Form("Budget");

f.setLayout(new BorderLayout());

332

The Components Of Codename One

f.addComponent(BorderLayout.CENTER, c);
return f;
}

5.33.Calendar
129

The Calendar
class allows us to display a traditional calendar picker and optionally
highlight days in various ways.
We normally recommend developers use the Picker UI rather than
use the calendar to pick a date. It looks better on the devices.
Simple usage of the Calendar class looks something like this:
Form hi = new Form("Calendar", new BorderLayout());
Calendar cld = new Calendar();

cld.addActionListener((e) -> Log.p("You picked: " + new

Date(cld.getSelectedDay())));
hi.add(BorderLayout.CENTER, cld);

129

https://www.codenameone.com/javadoc/com/codename1/ui/Calendar.html

333

The Components Of Codename One

Figure 5.93. The Calendar component

5.34.ToastBar
130

The ToastBar
class allows us to display none-obtrusive status messages to the user
at the bottom of the screen. This is useful for such things as informing the user of a
long-running task (like downloading a file in the background), or popping up an error
message that doesnt require a response from the user.
Simple usage of the ToastBar class looks something like this:
130

https://www.codenameone.com/javadoc/com/codename1/components/ToastBar.html

334

The Components Of Codename One

Status status = ToastBar.getInstance().createStatus();

status.setMessage("Downloading your file...");
status.show();
//

... Later on when download completes

status.clear();

Figure 5.94. ToastBar with message

We can show a progress indicator in the ToastBar like this:

335

The Components Of Codename One

Status status = ToastBar.getInstance().createStatus();

status.setMessage("Hello world");
status.setShowProgressIndicator(true);
status.show();

Figure 5.95. Status Message with Progress Bar

We can automatically clear a status message/progress after a timeout using the
setExpires method as such:

336

The Components Of Codename One

Status status = ToastBar.getInstance().createStatus();

status.setMessage("Hello world");
status.setExpires(3000);
it automatically clear

// only show the status for 3 seconds, then have

status.show();

We can also delay the showing of the status message using showDelayed as such:
Status status = ToastBar.getInstance().createStatus();
status.setMessage("Hello world");

status.showDelayed(300); // Wait 300 ms to show the status

// ... Some time later, clear the status... this may be before it shows at
all

status.clear();

337

The Components Of Codename One

Figure 5.96. ToastBar with a multiline message

5.35.SignatureComponent
The SignatureComponent
signature in the app.

131

provides a widget that allows users to draw their

Simple usage of the SignatureComponent class looks like:

131

https://www.codenameone.com/javadoc/com/codename1/components/SignatureComponent.html

338

The Components Of Codename One

Form hi = new Form("Signature Component");

hi.setLayout(new BoxLayout(BoxLayout.Y_AXIS));
hi.add("Enter Your Name:");
hi.add(new TextField());
hi.add("Signature:");

SignatureComponent sig = new SignatureComponent();

sig.addActionListener((evt)-> {
System.out.println("The signature was changed");
Image img = sig.getSignatureImage();

// Now we can do whatever we want with the image of this signature.

});
hi.addComponent(sig);
hi.show();

339

The Components Of Codename One

340

Figure 5.97. The signature Component

The Components Of Codename One

5.36.Accordion
The Accordion

132

displays collapsible content panels.

Simple usage of the Accordion class looks like:

Form f = new Form("Accordion", new BoxLayout(BoxLayout.Y_AXIS));
f.setScrollableY(true);

Accordion accr = new Accordion();

accr.addContent("Item1", new SpanLabel("The quick brown fox jumps over the

lazy dog\n"
+ "The quick brown fox jumps over the lazy dog"));

accr.addContent("Item2", new SpanLabel("The quick brown fox jumps over the

lazy dog\n"
+ "The quick brown fox jumps over the lazy dog\n "
+ "The quick brown fox jumps over the lazy dog\n "
+ "The quick brown fox jumps over the lazy dog\n "
+ ""));

accr.addContent("Item3", BoxLayout.encloseY(new Label("Label"), new

TextField(), new Button("Button"), new CheckBox("CheckBox")));

f.add(accr);
f.show();

132

https://www.codenameone.com/javadoc/com/codename1/components/Accordion.html

341

The Components Of Codename One

Figure 5.98. The Accordion Component

342

The Components Of Codename One

5.37.Floating Hint
133

FloatingHint
wraps a text component with a special container that can animate the
hint label into a title label when the text component is edited or has content within it.
Form hi = new Form("Floating Hint", BoxLayout.y());
TextField first = new TextField("", "First Field");

TextField second = new TextField("", "Second Field");

hi.add(new FloatingHint(first)).

add(new FloatingHint(second)).
add(new Button("Go"));

hi.show();

Figure 5.99. The FloatingHint component with one component that

contains text and another that doesnt

133

https://www.codenameone.com/javadoc/com/codename1/components/FloatingHint.html

343

Chapter6.Animations & Transitions

There are many ways to animate and liven the data within a Codename One application,
layout animations are probably chief among them. But first we need to understand
some basics such as layout reflows.

6.1.Layout Reflow
Layout in tools such as HTML is implicit, when you add something into the UI it is
automatically placed correctly. Other tools such as Codename One use explicit layout,
that means you have to explicitly request the UI to layout itself after making changes!
Like many such rules exceptions occur. E.g. if the device is rotated
or window size changes a layout will occur automatically.
When adding a component to a UI that is already visible, the component will not show
by default.
When adding a component to a form which isnt shown on the screen,
there is no need to tell the UI to repaint or reflow. This happens
implicitly.
The chief advantage of explicit layout is performance.
E.g. imagine adding 100 components to a form. If the form was laid out automatically,
layout would have happened 100 times instead of once when adding was finished. In
fact layout reflows are often considered the #1 performance issue for HTML/JavaScript
applications.
Smart layout reflow logic can alleviate some of the pains of the
automatic layout reflows however since the process is implicit its
almost impossible to optimize complex usages across browsers/
devices. A major JavaScript performance tip is to use absolute
positioning which is akin to not using layouts at all!
That is why, when you add components to a form that is already showing, you should
invoke revalidate() or animate the layout appropriately. This also enables the
layout animation behavior explained below.

344

Animations & Transitions

6.2.Layout Animations
To understand animations you need to understand a couple of things about
Codename One components. When we add a component to a container, its
generally just added but not positioned anywhere. A novice might notice the
setX / setY / setWidth / setHeight methods on a component and just try to
position it absolutely.
This wont work since these methods are meant for the layout manager, which is
implicitly invoked when a form is shown (internally in Codename One). The layout
manager uses these methods to position/size the components based on the hints given
to it.
If you add components to a form that is currently showing, it is your responsibility to
invoke revalidate / layoutContainer to arrange the newly added components
(see Layout Reflows).
animateLayout() method is a fancy form of revalidate that animates the
components into their laid out position. After changing the layout & invoking this method
the components move to their new sizes/positions seamlessly.
This sort of behavior creates a special case where setting the size/position makes
sense. When we set the size/position in the demo code here we are positioning the
components at the animation start position above the frame.
Form hi = new Form("Layout Animations", new BoxLayout(BoxLayout.Y_AXIS));
Button fall = new Button("Fall");
fall.addActionListener((e) -> {

for(int iter = 0 ; iter < 10 ; iter++) {

Label b = new Label ("Label " + iter);

b.setWidth(fall.getWidth());
b.setHeight(fall.getHeight());
b.setY(-fall.getHeight());
hi.add(b);

hi.getContentPane().animateLayout(20000);

});
hi.add(fall);

There are a couple of things that you should notice about this example:

345

Animations & Transitions

We used a button to do the animation rather than doing it on show. Since show()
implicitly lays out the components it wouldnt have worked correctly.
We used hi.getContentPane().animateLayout(20000); & not
hi.animateLayout(20000); . You need to animate the "actual" container and
Form is a special case.
This results in:

6.2.1.Unlayout Animations
While layout animations are really powerful effects for adding elements into the UI and
drawing attention to them. The inverse of removing an element from the UI is often
more important. E.g. when we delete or remove an element we want to animate it out.
Layout animations dont really do that since they will try to bring the animated item
into place. What we want is the exact opposite of a layout animation and that is the
"unlayout animation".
The "unlayout animation" takes a valid laid out state and shifts the components to an
invalid state that we defined in advance. E.g. we can fix the example above to flip the
"fall" button into a "rise" button when the buttons come into place and this will allow the
buttons to float back up to where they came from in the exact reverse order.
An unlayout animation always leaves the container in an invalidated
state.

Form hi = new Form("Layout Animations", new BoxLayout(BoxLayout.Y_AXIS));

Button fall = new Button("Fall");
fall.addActionListener((e) -> {

if(hi.getContentPane().getComponentCount() == 1) {
fall.setText("Rise");

for(int iter = 0 ; iter < 10 ; iter++) {

Label b = new Label ("Label " + iter);

b.setWidth(fall.getWidth());
b.setHeight(fall.getHeight());
b.setY(-fall.getHeight());
hi.add(b);

}
hi.getContentPane().animateLayout(20000);

} else {

fall.setText("Fall");

346

Animations & Transitions

for(int iter = 1 ; iter <
hi.getContentPane().getComponentCount() ; iter++) {
Component c = hi.getContentPane().getComponentAt(iter);
}

c.setY(-fall.getHeight());

hi.getContentPane().animateUnlayoutAndWait(20000, 255);

hi.removeAll();
hi.add(fall);
hi.revalidate();

});
hi.add(fall);

You will notice some similarities with the unlayout animation but the differences
represent the exact opposite of the layout animation:
We loop over existing components (not newly created ones)
We set the desired end position not the desired starting position
We used the AndWait variant of the animate unlayout call. We could have used
the async call as well.
After the animation completes we need to actually remove the elements since
the UI is now in an invalid position with elements outside of the screen but still
physically there!

6.2.2.Hiding & Visibility

A common trick for animating Components in Codename One is to set their preferred
size to 0 and then invoke animateLayout() thus triggering an animation to hide
said Component . There are several issues with this trick but one of the biggest ones
is the fact that setPreferredSize has been deprecated for quite a while.
Instead of using that trick you can use setHidden / isHidden who effectively
encapsulate this functionality and a bit more.
One of the issues setHidden tries to solve is the fact that preferred size doesnt
include the margin in the total and thus a component might still occupy space despite
being hidden. To solve this the margin is set to 0 when hiding and restored to its
original value when showing the component again by resetting the UIID (which resets
all style modifications).
This functionality might be undesirable which is why there is a version of the
setHidden method that accepts a boolean flag indicating whether the margin/
347

Animations & Transitions

UIID should be manipulated. You can effectively hide / show a component without
deprecated code using something like this:
Button toHide = new Button("Will Be Hidden");
Button hide = new Button("Hide It");
hide.addActionListener((e) -> {
hide.setEnabled(false);

boolean t = !toHide.isHidden();

});

toHide.setHidden(t);
toHide.getParent().animateLayoutAndWait(200);
toHide.setVisible(!t);
hide.setEnabled(true);

Notice that the code above uses setVisible() , which shouldnt

be confused with setHidden . setVisible() just toggles the
visibility of the component it would still occupy the same amount of
space

6.2.3.Synchronicity In Animations
Most animations have two or three variants:
Standard animation e.g. animateLayout(int)
And wait variant e.g. animateLayoutAndWait(int)
Callback variant e.g. animateUnlayout(int, int, Runnable)
The standard animation is invoked when we dont care about the completion of the
animation. We can do this for a standard animation.
The unlayout animations dont have a standard variant. Since they
leave the UI in an invalid state we must always do something once
the animation completes so a standard variant makes no sense
The AndWait variant blocks the calling thread until the animation completes. This
is really useful for sequencing animations one after the other e.g this code from the
kitchen sink demo:
arrangeForInterlace(effects);
effects.animateUnlayoutAndWait(800, 20);
effects.animateLayoutFade(800, 20);

348

Animations & Transitions

First the UI goes thru an "unlayout" animation, once that completes the layout itself is
performed.
The AndWait calls needs to be invoked on the Event Dispatch
Thread despite being "blocking". This is a common convention in
Codename One powered by a unique capability of Codename One:
invokeAndBlock .
You can learn more about invokeAndBlock in the EDT section.

The callback variant is similar to the invokeAndBlock variant but uses a more
conventional callback semantic which is more familiar to some developers. It accepts a
Runnable callback that will be invoked after the fact. E.g. we can change the unlayout
call from before to use the callback semantics as such:
hi.getContentPane().animateUnlayout(20000, 255, () -> {
hi.removeAll();
hi.add(fall);
hi.revalidate();
});

Animation Fade & Hierarchy

There are several additional variations on the standard animate methods. Several
methods accept a numeric fade argument. This is useful to fade out an element in
an "unlayout" operation or fade in a regular animation.
The value for the fade argument is a number between 0 and 255 where 0 represents
full transparency and 255 represents full opacity.
Some animate layout methods are hierarchy based. They work just like the regular
1
animateLayout methods but recurse into the entire Container hierarchy. These
methods work well when you have components in a nested hierarchy that need to
animate into place. This is demonstrated in the opening sequence of the kitchen sink
demo:
for(int iter = 0 ; iter < demoComponents.size() ; iter++) {

Component cmp = (Component)demoComponents.elementAt(iter);

if(iter < componentsPerRow) {

cmp.setX(-cmp.getWidth());

} else {
1

https://www.codenameone.com/javadoc/com/codename1/ui/Container.html

349

Animations & Transitions

if(iter < componentsPerRow * 2) {
cmp.setX(dw);

} else {
}

cmp.setX(-cmp.getWidth());

}
}
boxContainer.setShouldCalcPreferredSize(true);
boxContainer.animateHierarchyFade(3000, 30);

The demoComponents Vector contains components from separate containers and

this code would not work with a simple animate layout.
We normally recommend avoiding the hierarchy version. Its slower
but more importantly, its flaky. Since the size/position of the
Container might be affected by the layout the animation could get
clipped and skip. These are very hard issues to debug.

6.2.4.Sequencing Animations Via AnimationManager

2

All the animations go thru a per-form queue: the AnimationManager . This effectively
prevents two animations from mutating the UI in parallel so we wont have collisions
between two conflicting sides. Things get more interesting when we try to do something
like this:
cnt.add(myButton);

int componentCount = cnt.getComponentCount();

cnt.animateLayout(300);
cnt.removeComponent(myButton);

if(componentCount == cnt.getComponentCount()) {
}

// this will happen...

The reason this happens is that the second remove gets postponed to the end of the
animation so it wont break the animation. This works for remove and add operations
3
on a Container as well as other animations.
The simple yet problematic fix would be:
cnt.add(myButton);
2
3

https://www.codenameone.com/javadoc/com/codename1/ui/AnimationManager.html
https://www.codenameone.com/javadoc/com/codename1/ui/Container.html

350

Animations & Transitions

int componentCount = cnt.getComponentCount();
cnt.animateLayoutAndWait(300);
cnt.removeComponent(myButton);

if(componentCount == cnt.getComponentCount()) {
}

// this probably won't happen...

So why that might still fail?

4

Events come in constantly during the run of the EDT , so an event might come in that
might trigger an animation in your code. Even if you are on the EDT keep in mind that
you dont actually block it and an event might come in.
In those cases an animation might start and you might be unaware of that animation
and it might still be in action when you expect remove to work.

Animation Manager to the Rescue

5

AnimationManager has builtin support to fix this exact issue.

We can flush the animation queue and run synchronously after all the animations
finished and before new ones come in by using something like this:
cnt.add(myButton);

int componentCount = cnt.getComponentCount();

cnt.animateLayout(300);
cnt.getAnimationManager().flushAnimation(() -> {
cnt.removeComponent(myButton);

if(componentCount == cnt.getComponentCount()) {

});

// this shouldn't happen...

6.3.Low Level Animations

The Codename One event dispatch thread has a special animation pulse allowing
an animation to update its state and draw itself. Code can make use of this pulse to
implement repetitive polling tasks that have very little to do with drawing.
This is helpful since the callback will always occur on the event dispatch thread.
4
5

Event Dispatch Thread

https://www.codenameone.com/javadoc/com/codename1/ui/AnimationManager.html

351

Animations & Transitions

Every component in Codename One contains an animate() method that returns
6
a boolean value, you can also implement the Animation interface in an arbitrary
component to implement your own animation. In order to receive animation events you
need to register yourself within the parent form, it is the responsibility of the parent for
to call animate() .
If the animate method returns true then the animation will be painted (the paint
method of the Animation interface would be invoked).
It is important to deregister animations when they arent needed to
conserve battery life.
If you derive from a component, which has its own animation logic you might damage
its animation behavior by deregistering it, so tread gently with the low level APIs.
E.g. you can add additional animation logic using code like this:
myForm.registerAnimated(this);
private int spinValue;

public boolean animate() {

if(userStatusPending) {
spinValue++;

super.animate();
}
}

return true;

return super.animate();

6.3.1.Why Not Just Write Code In Paint?

Animations are comprised of two parts, the logic (deciding the position etc) and the
painting. The paint method should be dedicated to painting only, not to the actual
moving of the components.
The separation of concerns allows us to avoid redundant painting e.g. if animate didnt
trigger a change just return false to avoid the overhead related to animations.
We discuss low level animations in more details within the animation section of the
clock demo.
6

https://www.codenameone.com/javadoc/com/codename1/ui/animations/Animation.html

352

Animations & Transitions

6.4.Transitions
Transitions allow us to replace one component with another, most typically forms or
dialogs are replaced with a transition however a transition can be applied to replace
any arbitrary component.
Developers can implement their own custom transition and install it to components
7

by deriving the Transition

class, although most commonly the built in
8
CommonTransitions class is used for almost everything.
You can define transitions for forms/dialogs/menus globally either via the theme
9
constants or via the LookAndFeel class. Alternatively you can install a transition on
top-level components via setter methods.

In/Out Transitions
When defining a transition we define the entering transition and the exiting
transition. For most cases only one of those is necessary and we default to the
exiting (out transition) as a convention.
So for almost all cases the method setFormTransitonIn should go unused.
That API exists for some elaborate custom transitions that might need to have a
special effect both when transitioning in and out of a specific form. However, most
of these effects are easier to achieve with layout animations (e.g. components
dropping into place etc.).
In the case of Dialog the transition in shows its appearance and the transition
out shows its disposal. So in that case both transitions make a lot of sense.

Back/Forward Transitions
Transitions have a direction and can all be played either in incoming or outgoing
direction. A transition can be flipped (played in reverse) when we use an RTL
7
8
9

https://www.codenameone.com/javadoc/com/codename1/ui/animations/Transition.html
https://www.codenameone.com/javadoc/com/codename1/ui/animations/CommonTransitions.html
https://www.codenameone.com/javadoc/com/codename1/ui/plaf/LookAndFeel.html

353

Animations & Transitions

language
hierarchy.

10

or when we simply traverse backwards in the form navigation

Normally Form.show() displays the next Form with an incoming transition

based on the current RTL mode. If we use Form.showBack() it will play the
transition in reverse.
When working with high level animations you can select Slow Motion
option in the simulator to slow down animations and inspect their
details
Themes define the default transitions used when showing a form, these differ based
on the OS. In most platforms the default is Slide whereas in iOS the default is
SlideFade which slides the content pane and title while fading in/out the content of
the title area.

SlideFade is problematic without a title area. If you have a Form

that lacks a title area we would recommend to disable SlideFade
at least for that Form .
Check out the full set of theme constants in the Theme Constants Section.

6.4.1.Replace
To apply a transition to a component we can just use the Container.replace()
method as such:
Form hi = new Form("Replace", new BoxLayout(BoxLayout.Y_AXIS));
Button replace = new Button("Replace Pending");

Label replaceDestiny = new Label("Destination Replace");

hi.add(replace);
replace.addActionListener((e) -> {
replace.getParent().replaceAndWait(replace, replaceDestiny,
CommonTransitions.createCover(CommonTransitions.SLIDE_VERTICAL,
true, 800));
replaceDestiny.getParent().replaceAndWait(replaceDestiny, replace,
CommonTransitions.createUncover(CommonTransitions.SLIDE_VERTICAL,
true, 800));
});
10

Right to left/bidi language such as Hebrew or Arabic

354

Animations & Transitions

Replace even works when you have a layout constraint in place e.g.
replacing a component in a border layout will do the "right thing".
However, some layouts such as TableLayout might be tricky in
such cases so we recommend wrapping a potentially replaceable
Component in a border layout and replacing the content.
Container.replace() can also be used with a null transition at which point it

replaces instantly with no transition.

6.4.2.Slide Transitions
The slide transitions are used to move the Form/Component in a sliding motion to
the side or up/down. There are 4 basic types of slide transitions:
1. Slide - the most commonly used transition
2. Fast Slide - historically this provided better performance for old device types. It is
no longer recommended for newer devices
3. Slide Fade - the iOS default where the title area features a fade transition
4. Cover/Uncover - a type of slide transition where only the source or destination form
slides while the other remains static in place
The code below demonstrates the usage of all the main transitions:
Toolbar.setGlobalToolbar(true);

Form hi = new Form("Transitions", new BoxLayout(BoxLayout.Y_AXIS));

Style bg = hi.getContentPane().getUnselectedStyle();
bg.setBgTransparency(255);
bg.setBgColor(0xff0000);
Button showTransition = new Button("Show");
Picker pick = new Picker();

pick.setStrings("Slide", "SlideFade", "Cover", "Uncover", "Fade", "Flip");

pick.setSelectedString("Slide");
TextField duration = new TextField("10000", "Duration", 6,

TextArea.NUMERIC);
CheckBox horizontal = CheckBox.createToggle("Horizontal");
pick.addActionListener((e) -> {
String s = pick.getSelectedString().toLowerCase();
horizontal.setEnabled(s.equals("slide") || s.indexOf("cover") > -1);
});
horizontal.setSelected(true);
hi.add(showTransition).
add(pick).
add(duration).

355

Animations & Transitions

add(horizontal);
Form dest = new Form("Destination");

bg = dest.getContentPane().getUnselectedStyle();
bg.setBgTransparency(255);
bg.setBgColor(0xff);
dest.setBackCommand(
dest.getToolbar().addCommandToLeftBar("Back", null, (e) ->
hi.showBack()));
showTransition.addActionListener((e) -> {

int h = CommonTransitions.SLIDE_HORIZONTAL;
if(!horizontal.isSelected()) {
}

h = CommonTransitions.SLIDE_VERTICAL;

switch(pick.getSelectedString()) {
case "Slide":

hi.setTransitionOutAnimator(CommonTransitions.createSlide(h,
true, duration.getAsInt(3000)));
dest.setTransitionOutAnimator(CommonTransitions.createSlide(h,
true, duration.getAsInt(3000)));
break;

case "SlideFade":
hi.setTransitionOutAnimator(CommonTransitions.createSlideFadeTitle(true,
duration.getAsInt(3000)));
dest.setTransitionOutAnimator(CommonTransitions.createSlideFadeTitle(true,
duration.getAsInt(3000)));
break;

case "Cover":

hi.setTransitionOutAnimator(CommonTransitions.createCover(h,
true, duration.getAsInt(3000)));
dest.setTransitionOutAnimator(CommonTransitions.createCover(h,
true, duration.getAsInt(3000)));
break;

case "Uncover":

hi.setTransitionOutAnimator(CommonTransitions.createUncover(h,
true, duration.getAsInt(3000)));
dest.setTransitionOutAnimator(CommonTransitions.createUncover(h, true,
duration.getAsInt(3000)));
break;

case "Fade":
hi.setTransitionOutAnimator(CommonTransitions.createFade(duration.getAsInt(3000)));

356

Animations & Transitions

dest.setTransitionOutAnimator(CommonTransitions.createFade(duration.getAsInt(3000)));
break;

case "Flip":

hi.setTransitionOutAnimator(new FlipTransition(-1,

duration.getAsInt(3000)));

dest.setTransitionOutAnimator(new FlipTransition(-1,

duration.getAsInt(3000)));
break;

}
dest.show();

});
hi.show();

Figure 6.1. The slide transition moves both incoming and outgoing
forms together

Figure 6.2. The slide transition can be applied vertically as well

357

Animations & Transitions

Figure 6.3. Slide fade fades in the destination title while sliding the
content pane it is the default on iOS
SlideFade is problematic without a title area. If you have a Form
that lacks a title area we would recommend to disable SlideFade
at least for that Form .

Figure 6.4. With cover transitions the source form stays in place as
it is covered by the destination. This transition can be played both
horizontally and vertically

358

Animations & Transitions

Figure 6.5. Uncover is the inverse of cover. The destination form

stays in place while the departing form moves away

6.4.3.Fade & Flip Transitions

The fade transition is pretty trivial and only accepts a time value since it has no
directional context.

Figure 6.6. Fade transition is probably the simplest one around

11

The FlipTransition is also pretty simple but unlike the others it isnt a part of the
CommonTransitions . It has its own FlipTransition class.
This transition looks very different on devices as it uses native
perspective transforms available only there

Figure 6.7. Fade transition is probably the simplest one around

11

https://www.codenameone.com/javadoc/com/codename1/ui/animations/FlipTransition.html

359

Animations & Transitions

6.4.4.Bubble Transition
BubbleTransiton
growth motion.

12

morphs a component into another component using a circular

The BubbleTransition accepts the component that will grow into the bubble effect
as one of its arguments. Its generally designed for Dialog transitions although it
could work for more creative use cases:
The code below manipulates styles and look. This is done to make
the code more "self contained". Real world code should probably use
the theme
Form hi = new Form("Bubble");

Button showBubble = new Button("+");

showBubble.setName("BubbleButton");
Style buttonStyle = showBubble.getAllStyles();
buttonStyle.setBorder(Border.createEmpty());
buttonStyle.setFgColor(0xffffff);
buttonStyle.setBgPainter((g, rect) -> {
g.setColor(0xff);
int actualWidth = rect.getWidth();

int actualHeight = rect.getHeight();

int xPos, yPos;
int size;

if(actualWidth > actualHeight) {

yPos = rect.getY();
xPos = rect.getX() + (actualWidth - actualHeight) / 2;
size = actualHeight;

} else {

yPos = rect.getY() + (actualHeight - actualWidth) / 2;

xPos = rect.getX();
size = actualWidth;

}
g.setAntiAliased(true);
g.fillArc(xPos, yPos, size, size, 0, 360);

});
hi.add(showBubble);
hi.setTintColor(0);
showBubble.addActionListener((e) -> {

Dialog dlg = new Dialog("Bubbled");

dlg.setLayout(new BorderLayout());

12

https://www.codenameone.com/javadoc/com/codename1/ui/animations/BubbleTransition.html

360

Animations & Transitions

SpanLabel sl = new SpanLabel("This dialog should appear with a bubble

transition from the button", "DialogBody");

sl.getTextUnselectedStyle().setFgColor(0xffffff);
dlg.add(BorderLayout.CENTER, sl);
dlg.setTransitionInAnimator(new

BubbleTransition(500, "BubbleButton"));
dlg.setTransitionOutAnimator(new

BubbleTransition(500, "BubbleButton"));

dlg.setDisposeWhenPointerOutOfBounds(true);
dlg.getTitleStyle().setFgColor(0xffffff);

});

Style dlgStyle = dlg.getDialogStyle();

dlgStyle.setBorder(Border.createEmpty());
dlgStyle.setBgColor(0xff);
dlgStyle.setBgTransparency(0xff);
dlg.showPacked(BorderLayout.NORTH, true);

hi.show();

361

Animations & Transitions

Figure 6.8. Bubble transition converting a circular button to a Dialog

362

Animations & Transitions

6.4.5.Morph Transitions
Androids material design has a morphing effect where an element from the previous
form (activity) animates into a different component on a new activity. Codename One
13
has a morph effect in the Container class but it doesnt work as a transition between
forms and doesnt allow for multiple separate components to transition at once.

Figure 6.9. Morph Transition

To support this behavior we have the MorphTransition

14

class that provides this same

effect coupled with a fade to the rest of the UI (see Figure 6.9, Morph Transition).
Since the transition is created before the form exists we cant reference explicit
components within the form when creating the morph transition (in order to indicate
which component becomes which) so we need to refer to them by name. This means we
need to use setName(String) on the components in the source/destination forms
so the transition will be able to find them.
Form demoForm = new Form(currentDemo.getDisplayName());
demoForm.setScrollable(false);

demoForm.setLayout(new BorderLayout());

Label demoLabel = new Label(currentDemo.getDisplayName());

demoLabel.setIcon(currentDemo.getDemoIcon());
demoLabel.setName("DemoLabel");
demoForm.addComponent(BorderLayout.NORTH, demoLabel);
demoForm.addComponent(BorderLayout.CENTER, wrapInShelves(n));
....
demoForm.setBackCommand(backCommand);
demoForm.setTransitionOutAnimator(MorphTransition.create(3000).morph(currentDemo.getDisp
f.setTransitionOutAnimator(MorphTransition.create(3000).morph(currentDemo.getDisplayName
demoForm.show();

13
14

https://www.codenameone.com/javadoc/com/codename1/ui/Container.html
https://www.codenameone.com/javadoc/com/codename1/ui/animations/MorphTransition.html

363

Animations & Transitions

6.4.6.SwipeBackSupport
iOS7+ allows swiping back one form to the previous form, Codenmae One has an API
to enable back swipe transition:
SwipeBackSupport.bindBack(Form currentForm, LazyValue<Form> destination);

That one command will enable swiping back from currentForm . LazyValue
us to pass a value lazily:

15

allows

public interface LazyValue<T> {

}

public T get(Object... args);

This effectively allows us to pass a form and only create it as necessary (e.g. for a GUI
builder app we dont have the actual previous form instance), notice that the arguments
arent used for this case but will be used in other cases.
The code below should work for the transition sample above. Notice that this API was
designed to work with "Slide Fade" transition and might have issues with other transition
types:
SwipeBackSupport.bindBack(dest, (args) -> hi);

15

https://www.codenameone.com/javadoc/com/codename1/util/LazyValue.html

364

Chapter7.The EDT - Event Dispatch

Thread
7.1.What Is The EDT
Codename One allows developers to create as many threads as they want; however
in order to interact with the Codename One user interface components a developer
must use the EDT. The EDT stands for "Event Dispatch Thread" but it handles a lot
more than just "events".
The EDT is the main thread of Codename One, by using just one thread Codename
One can avoid complex synchronization code and focus on simple functionality that
assumes only one thread.
This has huge advantages for your code. You can normally assume
that all code will occur on a single thread and avoid complex
synchronization logic.
You can visualize the EDT as a loop such as this:
while(codenameOneRunning) {

performEventCallbacks();
performCallSeriallyCalls();
drawGraphicsAndAnimations();
sleepUntilNextEDTCycle();

Normally, every call you receive from Codename One will occur on the EDT. E.g. every
event, calls to paint(), lifecycle calls (start etc.) should all occur on the EDT.
This is pretty powerful, however it means that as long as your code is processing
nothing else can happen in Codename One!
If your code takes too long to execute then no painting or
event processing will occur during that time, so a call to
Thread.sleep() will actually stop everything!
The solution is pretty simple, if you need to perform something that requires intensive
CPU you can spawn a thread.
365

The EDT - Event Dispatch Thread

Codename Ones networking code automatically spawns its own network thread (see
1
the NetworkManager ). However, this also poses a problem
Codename One assumes all modifications to the UI are performed on the EDT but if
we spawned a separate thread. How do we force our modifications back into the EDT?
Codename

One

includes

methods

help
in
these
situations:
isEDT() ,
callSeriallyAndWait(Runnable) .

in

the

Display

class

to

callSerially(Runnable )

&

isEDT() is useful for generic code that needs to test whether the current code is
executing on the EDT.

7.2.Call Serially (And Wait)

callSerially(Runnable) should normally be called off the EDT (in a separate
thread), the run method within the submitted runnable will be invoked on the EDT.
The
Runnable
passed
to
the
callSerially
&
callSeriallyAndWait methods is not a Thread . We just use
the Runnable interface as a convenient callback interface.
// this code is executing in a separate thread
final String res = methodThatTakesALongTime();

Display.getInstance().callSerially(new Runnable() {
public void run() {

// this occurs on the EDT so I can make changes to UI components

});

resultLabel.setText(res);

You can write this code more concisely using Java 8 lambda code
as such:

// this code is executing in a separate thread

String res = methodThatTakesALongTime();

Display.getInstance().callSerially(() -> resultLabel.setText(res));
1
2

https://www.codenameone.com/javadoc/com/codename1/io/NetworkManager.html
https://www.codenameone.com/javadoc/com/codename1/ui/Display.html

366

The EDT - Event Dispatch Thread

This allows code to leave the EDT and then later on return to it to perform things within
the EDT.
The callSeriallyAndWait(Runnable) method blocks the current thread until
the method completes, this is useful for cases such as user notification e.g.:
// this code is executing in a separate thread
methodThatTakesALongTime();

Display.getInstance().callSeriallyAndWait(() -> {

// this occurs on the EDT so I can make changes to UI components

globalFlag = Dialog.show("Are You Sure?", "Do you want to

continue?", "Continue", "Stop");
});
// this code is executing the separate thread

// global flag was already set by the call above

if(!globalFlag) {
return;

}
otherMethod();

If you are unsure use callSerially . The use cases for

callSeriallyAndWait are very rare.

7.2.1.callSerially On The EDT

One of the misunderstood topics is why would we ever want to invoke callSerially
when we are still on the EDT. This is best explained by example. Say we have a button
that has quite a bit of functionality tied to its events e.g.:
1. A user added an action listener to show a Dialog.
2. A framework the user installed added some logging to the button.
3. The button repaints a release animation as its being released.
However, this might cause a problem if the first event that we handle (the dialog)
might cause an issue to the following events. E.g. a dialog will block the EDT (using
invokeAndBlock ), events will keep happening but since the event we are in "already
happened" the button repaint and the framework logging wont occur. This might also
happen if we show a form which might trigger logic that relies on the current form still
being present.
One of the solutions to this problem is to just wrap the action listeners body with a
callSerially . In this case the callSerially will postpone the event to the next
367

The EDT - Event Dispatch Thread

cycle (loop) of the EDT and let the other events in the chain complete. Notice that you
shouldnt use this normally since it includes an overhead and complicates application
flow, however when you run into issues in event processing we suggest trying this to
see if its the cause.
You should never invoke callSeriallyAndWait on the EDT since this
would effectively mean sleeping on the EDT. We made that method
throw an exception if its invoked from the EDT.

7.3.Debugging EDT Violations

There are two types of EDT violations:
1. Blocking the EDT thread so the UI performance is considerably slower.
2. Invoking UI code on a separate thread
Codename One provides a tool to help you detect some of these violations some
caveats may apply though
Its an imperfect tool. It might fire false positives meaning it might detect a violation for
perfectly legal code and it might miss some illegal calls. However, it is a valuable tool
in the process of detecting hard to track bugs that are sometimes only reproducible on
the devices (due to race condition behavior).
To activate this tool just select the Debug EDT menu option in the simulator and pick
the level of output you wish to receive:

368

The EDT - Event Dispatch Thread

Figure 7.1. Debug EDT

Full output will include stack traces to the area in the code that is suspected in the
violation.

7.4.Invoke And Block

Invoke and block is the exact opposite of callSeriallyAndWait() , it blocks the
EDT and opens a separate thread for the runnable call. This functionality is inspired
3
by the Foxtrot API, which is a remarkably powerful tool most Swing developers dont
know about.
This is best explained by an example. When we write typical code in Java we like that
code is in sequence as such:
doOperationA();
doOperationB();
doOperationC();

http://foxtrot.sourceforge.net/

369

The EDT - Event Dispatch Thread

This works well normally but on the EDT it might be a problem, if one of the operations
is slow it might slow the whole EDT (painting, event processing etc.). Normally we can
just move operations into a separate thread e.g.:
doOperationA();
new Thread() {

public void run() {

doOperationB();

}
}).start();
doOperationC();

Unfortunately, this means that operation C will happen in parallel to operation B which
might be a problem
E.g. instead of using operation names lets use a more "real world" example:
updateUIToLoadingStatus();
readAndParseFile();
updateUIWithContentOfFile();

Notice that the first and last operations must be conducted on the EDT but the
middle operation might be really slow! Since updateUIWithContentOfFile needs
readAndParseFile to occur before it starts doing the new thread wont be enough.
A simplistic approach is to do something like this:
updateUIToLoadingStatus();
new Thread() {

public void run() {

readAndParseFile();
updateUIWithContentOfFile();

}
}).start();

But updateUIWithContentOfFile should be executed on the EDT and not on a

random thread. So the right way to do this would be something like this:
updateUIToLoadingStatus();
new Thread() {

public void run() {

readAndParseFile();

370

The EDT - Event Dispatch Thread

Display.getInstance().callSerially(new Runnable() {
public void run() {

});

updateUIWithContentOfFile();

}
}).start();

This is perfectly legal and would work reasonably well, however it gets complicated as
we add more and more features that need to be chained serially after all these are just
3 methods!
Invoke and block solves this in a unique way you can get almost the exact same
behavior by using this:
updateUIToLoadingStatus();

Display.getInstance().invokeAndBlock(new Runnable() {
public void run() {
}

readAndParseFile();

});
updateUIWithContentOfFile();

Or this with Java 8 syntax:

updateUIToLoadingStatus();
Display.getInstance().invokeAndBlock(() -> readAndParseFile());
updateUIWithContentOfFile();

Invoke and block effectively blocks the current EDT in a legal way. It spawns a separate
thread that runs the run() method and when that run method completes it goes back
to the EDT.
All events and EDT behavior still work while invokeAndBlock is running, this is
because invokeAndBlock() keeps calling the main thread loop internally.
Notice that invokeAndBlock comes at a slight performance
penalty. Also notice that nesting invokeAndBlock calls (or over
using them) isnt recommended.
However, they are very convenient when working with multiple
threads/UI.
371

The EDT - Event Dispatch Thread

Even if you never call invokeAndBlock directly you are probably using it indirectly
4
in APIs such as Dialog that show a dialog while blocking the current thread e.g.:
public void actionPerformed(ActionEvent ev) {
// will return true if the user clicks "OK"

if(!Dialog.show("Question", "How Are You", "OK", "Not OK")) {

// ask what went wrong...
}

Notice that the dialog show method will block the calling thread until the user clicks
OK or Not OK
Other APIs such as NetworkManager.addToQueueAndWait()
also make use of this feature. Pretty much every "AndWait" method
or blocking method uses this API internally!
To explain how invokeAndBlock works we can return to the sample above of how the
EDT works:
while(codenameOneRunning) {

performEventCallbacks();
performCallSeriallyCalls();
drawGraphicsAndAnimations();
sleepUntilNextEDTCycle();

invokeAndBlock() works in a similar way to this pseudo code:

void invokeAndBlock(Runnable r) {
openThreadForR(r);

while(r is still running) {

performEventCallbacks();
performCallSeriallyCalls();
drawGraphicsAndAnimations();
sleepUntilNextEDTCycle();

https://www.codenameone.com/javadoc/com/codename1/ui/Dialog.html

372

The EDT - Event Dispatch Thread

So the EDT is effectively "blocked" but we "redo it" within the invokeAndBlock
method
As you can see this is a very simple approach for thread programming in UI, you
dont need to block your flow and track the UI thread. You can just program in a way
that seems sequential (top to bottom) but really uses multi-threading correctly without
blocking the EDT.

373

Chapter8.Monetization
Codename One tries to make the lives of software developers easier by integrating
several forms of built-in monetization solutions such as ad network support, in-apppurchase etc.
1

A lot of the monetization options are available as 3rd party cn1libs that you can install
thru the Codename One website.

8.1.Google Play Ads

The most effective network is the simplest banner ad support. To enable mobile ads just
2
create an ad unit in Admobs website, you should end up with the key similar to this:
ca-app-pub-8610616152754010/3413603324
To enable this for Android just define the android.googleAdUnitId=ca-apppub-8610616152754010/3413603324 in the build arguments and for iOS use the
same as in ios.googleAdUnitId . The rest is seamless, the right ad will be created
for you at the bottom of the screen and the form should automatically shrink to fit the
ad. This shrinking is implemented differently between iOS and Android due to some
constraints but the result should be similar and this should work reasonably well with
device rotation as well.

Figure 8.1. Google play ads

8.2.In App Purchase

Codename Ones in app purchase APIs try to generalize 3 different concepts for
purchase:
1
2

https://www.codenameone.com/cn1libs.html
https://apps.admob.com/?pli=1#monetize/adunit:create

374

Monetization
1. Googles in app purchase
2. Apples in app purchase
3. Mobile payments for physical goods
While all 3 approaches end up with the developer getting paid, all 3 take a different
approach to the same idea. Google and Apple work with products which you can
define and buy through their respective stores. You need to define the product in the
development environment and then send the user to purchase said product.
Once the product is purchased you receive an event that the purchase was completed
and you can act appropriately. On the other hand mobile payments are just a transfer
of a sum of money.
Both Googles and Apples stores prohibit the sale of physical goods via the stores,
so a mobile payment system needs to be used for those cases. This is where the
similarity ends between the Google & Apple approach. Google expects developers to
build their own storefront and provides developers with an API to extract the data in
order to construct said storefront. Apple expects the developers to open its storefront
to perform everything.
We tried to encode all 3 approaches into the purchase API which means you would
need to handle all 3 cases when working. Unfortunately these things are very hard to
simulate and can only be properly tested on the device.
So to organize the above we have:
1. Managed payments - payments are handled by the platform. We essentially buy
an item not transfer money (in app purchase).
2. Manual payments - we transfer money, there are no items involved.
final Purchase p = Purchase.getInAppPurchase();
if(p != null) {

if(p.isManualPaymentSupported()) {

purchaseDemo.addComponent(new Label("Manual Payment Mode"));

final TextField tf = new TextField("100");
tf.setHint("Send us money, thanks");

Button sendMoney = new Button("Send Us Money");

sendMoney.addActionListener(new ActionListener() {
public void actionPerformed(ActionEvent evt) {

p.pay(Double.parseDouble(tf.getText()), "USD");

375

Monetization
}

});
purchaseDemo.addComponent(tf);
purchaseDemo.addComponent(sendMoney);

if(p.isManagedPaymentSupported()) {

purchaseDemo.addComponent(new Label("Managed Payment Mode"));

for(int iter = 0 ; iter < ITEM_NAMES.length ; iter++) {
Button buy = new Button(ITEM_NAMES[iter]);
final String id = ITEM_IDS[iter];

buy.addActionListener(new ActionListener() {

public void actionPerformed(ActionEvent evt) {

}

p.purchase(id);

});
purchaseDemo.addComponent(buy);

} else {

purchaseDemo.addComponent(new Label("Payment unsupported on this

device"));

The item names in the demo code above should be hard coded and added to the
appropriate stores inventory. Which is a very platform specific process for iTunes and
Google play. Once this is done you should be able to issue a purchase request either
in the real or the sandbox store.

376

Chapter9.Graphics, Drawing, Images &

Fonts
This chapter covers the basics of drawing manually using the Graphics API :icons: font
Drawing is considered a low level API that might introduce some
platform fragmentation.

9.1.Basics - Where & How Do I Draw Manually?

1

The Graphics class is responsible for drawing basics, shapes, images and text, it is
never instantiated by the developer and is always passed on by the Codename One
API.
You can gain access to a Graphics using one of the following methods:
2

Derive Component or a subclass of Component - within Component there are

several methods that allow developers to modify the drawing behavior. These can
be overridden to change the way the component is drawn:
paint(Graphics) - invoked to draw the component, this can be overridden
to draw the component from scratch.
paintBackground(Graphics) / paintBackgrounds(Graphics)
these allow overriding the way the component background is painted although
you would probably be better off implementing a painter (see below).
paintBorder(Graphics) - allows overriding the process of drawing a
border, notice that border drawing might differ based on the style of the
component.
paintComponent(Graphics) - allows painting only the components
contents while leaving the default paint behavior to the style.

paintScrollbars(Graphics) , paintScrollbarX(Graphics) , paintScrollbarY(

allows overriding the behavior of scrollbar painting.
Implement the painter interface, this interface can be used as a GlassPane or
a background painter.
1
2

https://www.codenameone.com/javadoc/com/codename1/ui/Graphics.html
https://www.codenameone.com/javadoc/com/codename1/ui/Component.html

377

Graphics, Drawing, Images & Fonts

The painter interface is a simple interface that includes 1 paint method, this is
a useful way to allow developers to perform custom painting without subclassing
Component . Painters can be chained together to create elaborate paint behavior
3
by using the PainterChain class.
Glass pane - a glass pane allows developers to paint on top of the form painting.
This allows an overlay effect on top of a form.
For a novice it might seem that a glass pane is similar to overriding the Forms
paint method and drawing after super.paint(g) completed. This isnt the
case. When a component repaints (by invoking the repaint() method) only
4
that component is drawn and Form s paint() method wouldnt be invoked.
However, the glass pane painter is invoked for such cases and would work
exactly as expected.
5

Container has a glass pane method called paintGlass(Graphics) , which

can be overridden to provide a similar effect on a Container level. This is
6
especially useful for complex containers such as Table which draws its lines
using such a methodology.
Background painter - the background painter is installed via the style, by default
Codename installs a custom background painter of its own. Installing a custom
painter allows a developer to completely define how the background of the
component is drawn.
Notice that a lot of the background style behaviors can be achieved using styles
alone.
A common mistake developers make is overriding the
paint(Graphics) method of Form . The problem with that is that
form has child components which might request a repaint. To prevent
that either place a paintable component in the center of the Form ,
override the glasspane or the background painter.
A paint method can be implemented as such:
// hide the title
3
https://www.codenameone.com/javadoc/com/codename1/ui/painter/PainterChain.html
4
https://www.codenameone.com/javadoc/com/codename1/ui/Form.html
5
https://www.codenameone.com/javadoc/com/codename1/ui/Container.html
6
https://www.codenameone.com/javadoc/com/codename1/ui/table/Table.html

378

Graphics, Drawing, Images & Fonts

Form hi = new Form("", new BorderLayout());

hi.add(BorderLayout.CENTER, new Component() {

@Override

public void paint(Graphics g) {

// red color

g.setColor(0xff0000);
// paint the screen in red

g.fillRect(getX(), getY(), getWidth(), getHeight());

screen

// draw hi world in white text at the top left corner of the

g.setColor(0xffffff);
g.drawString("Hi World", getX(), getY());

});
hi.show();

379

Graphics, Drawing, Images & Fonts

Figure 9.1. Hi world demo code, notice that the blue bar on top is
the iOS7+ status bar

9.2.Glass Pane
The GlassPane `in Codename One is inspired by the Swing
`GlassPane & LayeredPane with quite a few twists. We tried to imagine how Swing
developers would have implemented the glass pane knowing what they do now about
painters and Swings learning curve. But first: what is the glass pane?
A typical Codename One application is essentially composed of 3 layers (this is a
gross simplification though), the background painters are responsible for drawing the
380

Graphics, Drawing, Images & Fonts

background of all components including the main form. The component draws its own
content (which might overrule the painter) and the glass pane paints last

Figure 9.2. Form layout graphic

Essentially the glass pane is a painter that allows us to draw an overlay on top of the
Codename One application.
Overriding the paint method of a form isnt a substitute for glasspane as it would
appear to work initially, when you enter a Form . However, when modifying an element
within the form only that element gets repainted not the entire Form !
7

So if we have a form with a Button and text drawn on top using the Forms paint
method it would get erased whenever the button gets focus.
The glass pane is called whenever a component gets painted, it only paints within the
clipping region of the component hence it wont break the rest of the components on
the Form which werent modified.
You can set a painter on a form using code like this:
7

https://www.codenameone.com/javadoc/com/codename1/ui/Button.html

381

Graphics, Drawing, Images & Fonts

hi.setGlassPane(new Painter() {
@Override

public void paint(Graphics g, Rectangle rect) {

});

Or you can use Java 8 lambdas to tighten the code a bit:

hi.setGlassPane((g, rect) -> {
});
8

PainterChain allows us to chain several painters together to perform different logical

tasks such as a validation painter coupled with a fade out painter. The sample below
shows a crude validation panel that allows us to draw error icons next to components
while exceeding their physical bounds as is common in many user interfaces
Form hi = new Form("Glass Pane", new BoxLayout(BoxLayout.Y_AXIS));

Style s = UIManager.getInstance().getComponentStyle("Label");
s.setFgColor(0xff0000);
s.setBgTransparency(0);
Image warningImage = FontImage.createMaterial(FontImage.MATERIAL_WARNING,
s).toImage();
TextField tf1 = new TextField("My Field");

tf1.getAllStyles().setMarginUnit(Style.UNIT_TYPE_DIPS);
tf1.getAllStyles().setMargin(5, 5, 5, 5);
hi.add(tf1);
hi.setGlassPane((g, rect) -> {
int x = tf1.getAbsoluteX() + tf1.getWidth();
int y = tf1.getAbsoluteY();

x -= warningImage.getWidth() / 2;
y += (tf1.getHeight() / 2 - warningImage.getHeight() / 2);
g.drawImage(warningImage, x, y);

});
hi.show();

https://www.codenameone.com/javadoc/com/codename1/ui/painter/PainterChain.html

382

Graphics, Drawing, Images & Fonts

Figure 9.3. The glass pane draws the warning sign on the border of
the component partially peeking out

9.3.Shapes & Transforms

The graphics API provides a high performance shape API that allows drawing arbitrary
shapes by defining paths and curves and caching the shape drawn in the GPU.

9.4.Device Support
Shapes and transforms are available on most smartphone platforms with some caveats
for the current Windows Phone port.
Notice that perspective transform is missing from the desktop/simulator port.
Unfortunately there is no real equivalent to perspective transform in JavaSE that we
could use.

9.5.A 2D Drawing App

We can demonstrate shape drawing with a simple example of a drawing app, that allows
the user to tap the screen to draw a contour picture.
9

The app works by simply keeping a GeneralPath in memory, and continually adding
points as bezier curves. Whenever a point is added, the path is redrawn to the screen.
The center of the app is the DrawingCanvas class, which extends Component
public class DrawingCanvas extends Component {
9

https://www.codenameone.com/javadoc/com/codename1/ui/geom/GeneralPath.html
10
https://www.codenameone.com/javadoc/com/codename1/ui/Component.html

383

10

Graphics, Drawing, Images & Fonts

GeneralPath p = new GeneralPath();
int strokeColor = 0x0000ff;
int strokeWidth = 10;

public void addPoint(float x, float y){

}

// To be written

@Override

protected void paintBackground(Graphics g) {

super.paintBackground(g);

Stroke stroke = new Stroke(

strokeWidth,
Stroke.CAP_BUTT,
Stroke.JOIN_ROUND, 1f

);
g.setColor(strokeColor);
// Draw the shape

g.drawShape(p, stroke);
}
@Override

public void pointerPressed(int x, int y) {

addPoint(x-getParent().getAbsoluteX(), ygetParent().getAbsoluteY());
}
}

Conceptually this is very basic component. We will be overriding the

11
paintBackground() method to draw the path. We keep a reference to a
12
13
GeneralPath object (which is the concrete implementation of the Shape interface
in Codename One) to store each successive point in the drawing. We also parametrize
the stroke width and color.
The implementation of the paintBackground() method (shown above) should be
fairly straight forward. It creates a stroke of the appropriate width, and sets the color on
the graphics context. Then it calls drawShape() to render the path of points.
11

https://www.codenameone.com/javadoc/com/codename1/ui/

Component.html#paintBackground(com.codename1.ui.Graphics)
12
https://www.codenameone.com/javadoc/com/codename1/ui/geom/GeneralPath.html
13
https://www.codenameone.com/javadoc/com/codename1/ui/geom/Shape.html

384

Graphics, Drawing, Images & Fonts

9.5.1.Implementing addPoint()
The addPoint method is designed to allow us to add points to the drawing. A simple
implementation that uses straight lines rather than curves might look like this:
private float lastX = -1;
private float lastY = -1;
public void addPoint(float x, float y) {
if (lastX == -1) {

// this is the first point... don't draw a line yet

p.moveTo(x, y);

} else {

p.lineTo(x, y);

}
lastX = x;
lastY = y;

repaint();

We introduced a couple house-keeping member vars ( lastX and lastY ) to store

the last point that was added so that we know whether this is the first tap or a
subsequent tap. The first tap triggers a moveTo() call, whereas subsequent taps
trigger lineTo() calls, which draw lines from the last point to the current point.
A drawing might look like this:

385

Graphics, Drawing, Images & Fonts

Figure 9.4. lineTo example

386

Graphics, Drawing, Images & Fonts

9.5.2.Using Bezier Curves

Our previous implementation of addPoint() used lines for each segment of the drawing.
Lets make an adjustment to allow for smoother edges by using quadratic curves
instead of lines.
Codename Ones GeneralPath class includes two methods for drawing curves:
14

1. quadTo() : Appends a quadratic bezier curve. It takes 2 points: a control point,

and an end point.
15

2. curveTo() : Appends a cubic bezier curve, taking 3 points: 2 control points,

and an end point.
See the General Path javadocs

16

for the full API.

17

We will make use of the quadTo()

method to append curves to the drawing as

follows:

private boolean odd=true;

public void addPoint(float x, float y){

if ( lastX == -1 ){
p.moveTo(x, y);

} else {

float controlX = odd ? lastX : x;

float controlY = odd ? y : lastY;

p.quadTo(controlX, controlY, x, y);

}
odd = !odd;
lastX = x;
lastY = y;
repaint();

This change should be fairly straight forward except, perhaps, the business with the
odd variable. Since quadratic curves require two points (in addition to the implied
14

https://www.codenameone.com/javadoc/com/codename1/ui/geom/GeneralPath.html#quadTo(float,

%20float,%20float,%20float)
15
https://www.codenameone.com/javadoc/com/codename1/ui/geom/GeneralPath.html#curveTo(float,
%20float,%20float,%20float,%20float,%20float)
16
https://www.codenameone.com/javadoc/com/codename1/ui/geom/GeneralPath.html
17
https://www.codenameone.com/javadoc/com/codename1/ui/geom/GeneralPath.html#quadTo(float,
%20float,%20float,%20float)

387

Graphics, Drawing, Images & Fonts

starting point), we cant simply take the last tap point and the current tap point. We need
a point between them to act as a control point. This is where we get the curve from.
The control point works by exerting a sort of "gravity" on the line segment, to pull the
line towards it. This results in the line being curved. I use the odd marker to alternate
the control point between positions above the line and below the line.
A drawing from the resulting app looks like:

388

Graphics, Drawing, Images & Fonts

389
Figure 9.5. Result of quadTo example

Graphics, Drawing, Images & Fonts

9.5.3.Detecting Platform Support

The DrawingCanvas example is a bit naive in that it assumes that the device

supports the shape API. If I were to run this code on a device that doesnt
18
support the Shape
API, it would just draw a blank canvas where I expected
my shape to be drawn. You can fall back gracefully if you make use of the
19
Graphics.isShapeSupported()
method. E.g.
@Override

protected void paintBackground(Graphics g) {

super.paintBackground(g);

if ( g.isShapeSupported() ){

// do my shape drawing code here

} else {

// draw an alternate representation for device

// that doesn't support shapes.

// E.g. you could defer to the Pisces

}

// library in this case

9.6.Transforms
20

The Graphics class has included limited support for 2D transformations for some
time now including scaling, rotation, and translation:
scale(x,y) : Scales drawing operations by a factor in each direction.
translate(x,y) : Translates drawing operations by an offset in each direction.
rotate(angle) : Rotates about the origin.
rotate(angle, px, py) : Rotates about a pivot point.
scale() and rotate() methods are only available on platforms
that support Affine transforms. See table X for a compatibility list.
18
19
20

https://www.codenameone.com/javadoc/com/codename1/ui/geom/Shape.html
https://www.codenameone.com/javadoc/com/codename1/ui/Graphics.html#isShapeSupported()
https://www.codenameone.com/javadoc/com/codename1/ui/Graphics.html

390

Graphics, Drawing, Images & Fonts

9.6.1.Device Support
As of this writing, not all devices support transforms (i.e. scale() and rotate() ).
The following is a list of platforms and their respective levels of support.

Table 9.1. Transforms Device Support

Platform

Affine Supported

Simulator

Yes

iOS

Yes

Android

Yes

JavaScript

Yes

J2ME

No

BlackBerry (4.2 & 5)

No

Windows Phone

No (pending)
21

You can check if a particular Graphics

the isAffineSupported() method.

context supports rotation and scaling using

e.g.
public void paint(Graphics g){

if ( g.isAffineSupported() ){

// Do something that requires rotation and scaling

} else {

// Fallback behavior here

9.7.Example: Drawing an Analog Clock

In the following sections, I will implement an analog clock component. This will
demonstrate three key concepts in Codename Ones graphics:
1. Using the GeneralPath class for drawing arbitrary shapes.
2. Using Graphics.translate() to translate our drawing position by an offset.
3. Using Graphics.rotate() to rotate our drawing position.
21

https://www.codenameone.com/javadoc/com/codename1/ui/Graphics.html

391

Graphics, Drawing, Images & Fonts

There are three separate things that need to be drawn in a clock:
1. The tick marks. E.g. most clocks will have a tick mark for each second, larger tick
marks for each hour, and sometimes even larger tick marks for each quarter hour.
2. The numbers. We will draw the clock numbers (1 through 12) in the appropriate
positions.
3. The hands. We will draw the clock hands to point at the appropriate points to display
the current time.

9.7.1.The AnalogClock Component

22

Our clock will extend the Component

method to draw the clock as follows:

class, and override the paintBackground()

public class AnalogClock extends Component {

Date currentTime = new Date();
@Override

public void paintBackground(Graphics g) {

// Draw the clock in this method

9.7.2.Setting up the Parameters

Before we actually draw anything, lets take a moment to figure out what values we
need to know in order to draw an effective clock. Minimally, we need two values:
1. The center point of the clock.
2. The radius of the clock.
In addition, I am adding the following parameters to to help customize how the clock
is rendered:
1. The padding (i.e. the space between the edge of the component and the edge of
the clock circle.
2. The tick lengths. I will be using 3 different lengths of tick marks on this clock. The
longest ticks will be displayed at quarter points (i.e. 12, 3, 6, and 9). Slightly shorter
22

https://www.codenameone.com/javadoc/com/codename1/ui/Component.html

392

Graphics, Drawing, Images & Fonts

ticks will be displayed at the five-minute marks (i.e. where the numbers appear),
and the remaining marks (corresponding with seconds) will be quite short.
// Hard code the padding at 10 pixels for now
double padding = 10;
// Clock radius

double r = Math.min(getWidth(), getHeight())/2-padding;

// Center point.

double cX = getX()+getWidth()/2;

double cY = getY()+getHeight()/2;
//Tick Styles

int tickLen = 10;

// short tick

int medTickLen = 30;

// at 5-minute intervals

int longTickLen = 50; // at the quarters

int tickColor = 0xCCCCCC;

Stroke tickStroke = new Stroke(2f, Stroke.CAP_BUTT,

Stroke.JOIN_ROUND, 1f);

9.7.3.Drawing the Tick Marks

23

For the tick marks, we will use a single GeneralPath

object, making use of the
moveTo() and lineTo() methods to draw each individual tick.
// Draw a tick for each "second" (1 through 60)
for ( int i=1; i<= 60; i++){

// default tick length is short

int len = tickLen;

if ( i % 15 == 0 ){

// Longest tick on quarters (every 15 ticks)

len = longTickLen;

} else if ( i % 5 == 0 ){

// Medium ticks on the '5's (every 5 ticks)

len = medTickLen;

double di = (double)i; // tick num as double for easier math

// Get the angle from 12 O'Clock to this tick (radians)
23

https://www.codenameone.com/javadoc/com/codename1/ui/geom/GeneralPath.html

393

Graphics, Drawing, Images & Fonts

double angleFrom12 = di/60.0*2.0*Math.PI;
// Get the angle from 3 O'Clock to this tick

// Note: 3 O'Clock corresponds with zero angle in unit circle

// Makes it easier to do the math.

double angleFrom3 = Math.PI/2.0-angleFrom12;

// Move to the outer edge of the circle at correct position
// for this tick.
ticksPath.moveTo(

(float)(cX+Math.cos(angleFrom3)*r),

);

(float)(cY-Math.sin(angleFrom3)*r)

// Draw line inward along radius for length of tick mark

ticksPath.lineTo(

(float)(cX+Math.cos(angleFrom3)*(r-len)),

);

(float)(cY-Math.sin(angleFrom3)*(r-len))

// Draw the full shape onto the graphics context.

g.setColor(tickColor);
g.drawShape(ticksPath, tickStroke);

This example uses a little bit of trigonometry to calculate the (x,y)

coordinates of the tick marks based on the angle and the radius. If
math isnt your thing, dont worry. This example just makes use of
the identities: x=r*cos and y=r*sin .
At this point our clock should include a series of tick marks orbiting a blank center as
shown below:

394

Graphics, Drawing, Images & Fonts

Figure 9.6. Drawing tick marks on the watch face

9.7.4.Drawing the Numbers

The Graphics.drawString(str, x, y) method allows you to draw text at any
point of a component. The tricky part here is calculating the correct x and y values
for each string so that the number appears in the correct location.
For the purposes of this tutorial, we will use the following strategy. For each number
(1 through 12):
1. Use the Graphics.translate(x,y) method to apply a translation from the
clocks center point to the point where the number should appear.
2. Draw number (using drawString() ) at the clocks center. It should be rendered
at the correct point due to our translation.
395

Graphics, Drawing, Images & Fonts

3. Invert the translation performed in step 1.
for ( int i=1; i<=12; i++){

// Calculate the string width and height so we can center it properly

String numStr = ""+i;

int charWidth = g.getFont().stringWidth(numStr);

int charHeight = g.getFont().getHeight();
double di = (double)i;

// number as double for easier math

// Calculate the position along the edge of the clock where the number

should

// be drawn

// Get the angle from 12 O'Clock to this tick (radians)

double angleFrom12 = di/12.0*2.0*Math.PI;

// Get the angle from 3 O'Clock to this tick

// Note: 3 O'Clock corresponds with zero angle in unit circle

// Makes it easier to do the math.

double angleFrom3 = Math.PI/2.0-angleFrom12;

// Get diff between number position and clock center

int tx = (int)(Math.cos(angleFrom3)*(r-longTickLen));

int ty = (int)(-Math.sin(angleFrom3)*(r-longTickLen));
// For 6 and 12 we will shift number slightly so they are more even
if ( i == 6 ){

ty -= charHeight/2;

} else if ( i == 12 ){
}

ty += charHeight/2;

// Translate the graphics context by delta between clock center and

// number position
g.translate(
tx,
ty
);

// Draw number at clock center.

g.drawString(numStr, (int)cX-charWidth/2, (int)cY-charHeight/2);

// Undo translation

g.translate(-tx, -ty);

396

Graphics, Drawing, Images & Fonts

This example is, admittedly, a little contrived to allow for a

demonstration of the Graphics.translate() method. We could
have just as easily passed the exact location of the number to
drawString() rather than draw at the clock center and translate
to the correct location.

Now, we should have a clock with tick marks and numbers as shown below:

Figure 9.7. Drawing the numbers on the watch face

24

https://www.codenameone.com/javadoc/com/codename1/ui/geom/GeneralPath.html

397

Graphics, Drawing, Images & Fonts

9.7.5.Drawing the Hands

The clock will include three hands: Hour, Minute, and Second. We will use a separate
24

GeneralPath object for each hand. For the positioning/angle of each, I will employ
the following strategy:
1. Draw the hand at the clock center pointing toward 12 (straight up).
2. Translate the hand slightly down so that it overlaps the center.
3. Rotate the hand at the appropriate angle for the current time, using the clock center
as a pivot point.
Drawing the Second Hand:
For the "second" hand, we will just use a simple line from the clock center to the inside
edge of the medium tick mark at the 12 oclock position.
GeneralPath secondHand = new GeneralPath();
secondHand.moveTo((float)cX, (float)cY);

secondHand.lineTo((float)cX, (float)(cY-(r-medTickLen)));

And we will translate it down slightly so that it overlaps the center. This translation will be
performed on the GeneralPath object directly rather than through the Graphics
context:
Shape translatedSecondHand = secondHand.createTransformedShape(
Transform.makeTranslation(0f, 5)
);

Rotating the Second Hand::

The rotation of the second hand will be performed in the Graphics context via the
rotate(angle, px, py) method. This requires us to calculate the angle. The px
and py arguments constitute the pivot point of the rotation, which, in our case will be
the clock center.
The rotation pivot point is expected to be in absolute screen
coordinates rather than relative coordinates of the component.
Therefore we need to get the absolute clock center position in order
to perform the rotation.
398

Graphics, Drawing, Images & Fonts

// Calculate the angle of the second hand

Calendar calendar = Calendar.getInstance(TimeZone.getDefault());

double second = (double)(calendar.get(Calendar.SECOND));
double secondAngle = second/60.0*2.0*Math.PI;
// Get absolute center position of the clock
double absCX = getAbsoluteX()+cX-getX();
double absCY = getAbsoluteY()+cY-getY();
g.rotate((float)secondAngle, (int)absCX, (int)absCY);
g.setColor(0xff0000);
g.drawShape(
translatedSecondHand,

new Stroke(2f, Stroke.CAP_BUTT, Stroke.JOIN_BEVEL, 1f)

);
g.resetAffine();

Remember to call resetAffine() after youre done with the

rotation, or you will see some unexpected results on your form.
Drawing the Minute And Hour Hands:
The mechanism for drawing the hour and minute hands is largely the same as for the
minute hand. There are a couple of added complexities though:
1. Well make these hands trapezoidal, and almost triangular rather than just using
a simple line. Therefore the GeneralPath construction will be slightly more
complex.
2. Calculation of the angles will be slightly more complex because they need to take
into account multiple parameters. E.g. The hour hand angle is informed by both the
hour of the day and the minute of the hour.
The remaining drawing code is as follows:
// Draw the minute hand

GeneralPath minuteHand = new GeneralPath();

minuteHand.moveTo((float)cX, (float)cY);

minuteHand.lineTo((float)cX+6, (float)cY);

minuteHand.lineTo((float)cX+2, (float)(cY-(r-tickLen)));
minuteHand.lineTo((float)cX-2, (float)(cY-(r-tickLen)));
minuteHand.lineTo((float)cX-6, (float)cY);

399

Graphics, Drawing, Images & Fonts

minuteHand.closePath();
// Translate the minute hand slightly down so it overlaps the center
Shape translatedMinuteHand = minuteHand.createTransformedShape(
Transform.makeTranslation(0f, 5)
);
double minute = (double)(calendar.get(Calendar.MINUTE)) +
(double)(calendar.get(Calendar.SECOND))/60.0;

double minuteAngle = minute/60.0*2.0*Math.PI;

// Rotate and draw the minute hand

g.rotate((float)minuteAngle, (int)absCX, (int)absCY);

g.setColor(0x000000);
g.fillShape(translatedMinuteHand);
g.resetAffine();

// Draw the hour hand

GeneralPath hourHand = new GeneralPath();

hourHand.moveTo((float)cX, (float)cY);

hourHand.lineTo((float)cX+4, (float)cY);

hourHand.lineTo((float)cX+1, (float)(cY-(r-longTickLen)*0.75));
hourHand.lineTo((float)cX-1, (float)(cY-(r-longTickLen)*0.75));
hourHand.lineTo((float)cX-4, (float)cY);
hourHand.closePath();

Shape translatedHourHand = hourHand.createTransformedShape(

Transform.makeTranslation(0f, 5)
);
//Calendar cal = Calendar.getInstance().get

double hour = (double)(calendar.get(Calendar.HOUR_OF_DAY)%12) +

(double)(calendar.get(Calendar.MINUTE))/60.0;

double angle = hour/12.0*2.0*Math.PI;

g.rotate((float)angle, (int)absCX, (int)absCY);

g.setColor(0x000000);
g.fillShape(translatedHourHand);
g.resetAffine();

9.7.6.The Final Result

At this point, we have a complete clock as shown below:
400

Graphics, Drawing, Images & Fonts

Figure 9.8. The final result - fully rendered watch face

9.7.7.Animating the Clock

The current clock component is cool, but it is static. It just displays the time at the point
the clock was created. We discussed low level animations in the animation section of
the guide, here we will show a somewhat more elaborate example.
In order to animate our clock so that it updates once per second, we only need to do
two things:
1. Implement the animate() method to indicate when the clock needs to be
updated/re-drawn.
2. Register the component with the form so that it will receive animation "pulses".
The animate() method in the AnalogClock class:
401

Graphics, Drawing, Images & Fonts

Date currentTime = new Date();

long lastRenderedTime = 0;
@Override

public boolean animate() {

if ( System.currentTimeMillis()/1000 != lastRenderedTime/1000){
currentTime.setTime(System.currentTimeMillis());

}
}

return true;

return false;

This method will be invoked on each "pulse" of the EDT. It checks the last time the
clock was rendered and returns true only if the clock hasnt been rendered in the
current "time second" interval. Otherwise it returns false. This ensures that the clock
will only be redrawn when the time changes.

9.8.Starting and Stopping the Animation

Animations
can
be
started
and
stopped
via
the
Form.registerAnimated(component)
and
Form.deregisterAnimated(component) methods. We chose to encapsulate
these calls in start() and stop() methods in the component as follows:
public void start(){
}

getComponentForm().registerAnimated(this);

public void stop(){

}

getComponentForm().deregisterAnimated(this);

So the code to instantiate the clock, and start the animation would be something like:
AnalogClock clock = new AnalogClock();
parent.addComponent(clock);
clock.start();

402

Graphics, Drawing, Images & Fonts

9.9.Shape Clipping
Clipping is one of the core tenants of graphics programming, you define the boundaries
for drawing and when you exceed said boundaries things arent drawn. Shape clipping
allows us to clip based on any arbitrary Shape and not just a rectangle, this allows
some unique effects generated in runtime.
E.g. this code allows us to draw a rather complex image of duke:
Image duke = null;
try {

// duke.png is just the default Codename One icon copied into place
duke = Image.createImage("/duke.png");

} catch(IOException err) {
}

Log.e(err);

final Image finalDuke = duke;

Form hi = new Form("Shape Clip");
// We create a 50 x 100 shape, this is arbitrary since we can scale it
easily

GeneralPath path = new GeneralPath();

path.moveTo(20,0);
path.lineTo(30, 0);
path.lineTo(30, 100);
path.lineTo(20, 100);
path.lineTo(20, 15);
path.lineTo(5, 40);
path.lineTo(5, 25);
path.lineTo(20,0);

Stroke stroke = new Stroke(0.5f, Stroke.CAP_ROUND, Stroke.JOIN_ROUND, 4);

hi.getContentPane().getUnselectedStyle().setBgPainter((Graphics g,
Rectangle rect) -> {
g.setColor(0xff);
float widthRatio = ((float)rect.getWidth()) / 50f;

float heightRatio = ((float)rect.getHeight()) / 100f;

g.scale(widthRatio, heightRatio);

g.translate((int)(((float)rect.getX()) / widthRatio), (int)

(((float)rect.getY()) / heightRatio));

g.setClip(path);
g.setAntiAliased(true);
g.drawImage(finalDuke, 0, 0, 50, 100);

403

Graphics, Drawing, Images & Fonts

g.setClip(path.getBounds());
g.drawShape(path, stroke);

g.translate(-(int)(((float)rect.getX()) / widthRatio), -(int)

(((float)rect.getY()) / heightRatio));
});

g.resetAffine();

hi.show();

Figure 9.9. Shape Clipping used to clip the image of duke within the
given shape
Notice that this functionality isnt available on all platforms so
you normally need to test if shaped clipping is supported using
25
isShapeClipSupported() .

9.10.The Coordinate System

The Codename One coordinate system follows the example of Swing (and many other
- but not all- graphics libraries) and places the origin in the upper left corner of the
screen. X-values grow to the right, and Y-values grow downward as illustrated below:
25

https://www.codenameone.com/javadoc/com/codename1/ui/Graphics.html#isShapeClipSupported--

404

Graphics, Drawing, Images & Fonts

Figure 9.10. The Codename One graphics coordinate space

Therefore the screen origin is at the top left corner of the screen. Given this information,
26
consider the method call on the Graphics context g :
g.drawRect(10,10, 100, 100);

Where would this rectangle be drawn on the screen?

If you answered something something like "10 pixels from the top, and 10 pixels from
the left of the screen", you might be right. It depends on whether the graphics has a
translation or transform applied to it. If there is currently a translation of (20,20) (i.e.
20 pixels to the right, and 20 pixels down), then the rectangle would be rendered at
(30, 30) .
You can always find out the current translation of the graphics context using the
Graphics.getTranslateX() and Graphics.getTranslateY() methods:
// Find out the current translation
int currX = g.getTranslateX();
int currY = g.getTranslateY();

26

https://www.codenameone.com/javadoc/com/codename1/ui/Graphics.html

405

Graphics, Drawing, Images & Fonts

// Reset the translation to zeroes
g.translate(-currX, -currY);

// Now we are working in absolute screen coordinates

g.drawRect(10, 10, 100, 100);

// This rectangle should now be drawn at the exact screen

// coordinates (10,10).

//Restore the translation

g.translate(currX, currY);

This example glosses over issues such as clipping and transforms

which may cause it to not work as you expect. E.g. When painting
a component inside its paint() method, there is a clip applied to
the context so that only the content you draw within the bounds of
the component will be seen.
If, in addition, there is a transform applied that rotates the context 45 degrees clockwise,
then the rectangle will be drawn at a 45 degree angle with its top left corner somewhere
on the left edge of the screen.
Luckily you usually dont have to worry about the exact screen coordinates for the things
you paint. Most of the time, you will only be concerned with relative coordinates.

9.10.1.Relative Coordinates
Usually, when you are drawing onto a Graphics context, you are doing so within
the context of a Components paint() method (or one of its variants). In this case,
you generally dont care what the exact screen coordinates are of your drawing. You
are only concerned with their relative location within the coordinate. You can leave the
positioning (and even sizing) of the coordinate up to Codename One. Thank you for
reading.
27

To demonstrate this, lets create a simple component called Rectangle component,

that simply draws a rectangle on the screen. We will use the components position and
size to dictate the size of the rectangle to be drawn. And we will keep a 5 pixel padding
between the edge of the component and the edge of our rectangle.
class RectangleComponent extends Component {
27

https://www.codenameone.com/javadoc/com/codename1/ui/geom/Rectangle.html

406

Graphics, Drawing, Images & Fonts

public void paint(Graphics g){

g.setColor(0x0000ff);
g.drawRect(getX()+5, getY()+5, getWidth()-10, getHeight()-10);

The result is as follows:

407

Graphics, Drawing, Images & Fonts

Figure 9.11. The rectangle component

The x and y coordinates that are passed to the
drawRect(x,y,w,h) method are relative to the components

408

Graphics, Drawing, Images & Fonts

parents origin not the component itself .. its parent. This is why
we the x position is getX()+5 and not just 5.

9.10.2.Transforms and Rotations

Unlike the Graphics drawXXX primitives, methods for setting transformations,
including scale(x,y) and rotate(angle) , are always applied in terms of screen
coordinates. This can be confusing at first, because you may be unsure whether to
provide a relative coordinate or an absolute coordinate for a given method.
The general rule is:
1. All coordinates passed to the drawXXX() and fillXXX() methods will be subject
to the graphics contexts transform and translation settings.
2. All coordinates passed to the contexts transformation settings are
considered to be screen coordinates, and are not subject to current transform
and translation settings.
Lets take our RectangleComponent as an example. Suppose we want to rotate the
rectangle by 45 degrees, our first attempt might look something like:
class RectangleComponent extends Component {
@Override

protected Dimension calcPreferredSize() {

}

return new Dimension(250,250);

public void paint(Graphics g) {

g.setColor(0x0000ff);

g.rotate((float) (Math.PI / 4.0));

g.drawRect(getX() + 5, getY() + 5, getWidth() - 10,

getHeight() - 10);

g.rotate(-(float) (Math.PI / 4.0));

When performing rotations and transformations inside a paint()

method, always remember to revert your transformations at the end
of the method so that it doesnt pollute the rendering pipeline for
subsequent components.
409

Graphics, Drawing, Images & Fonts

The behavior of this rotation will vary based on where the component is rendered on
the screen. To demonstrate this, lets try to place five of these components on a form
inside a BorderLayout

28

and see how it looks:

class MyForm extends Form {

public MyForm() {

super("Rectangle Rotations");
for ( int i=0; i< 10; i++ ){

this.addComponent(new RectangleComponent());

The result is as follows:

28

https://www.codenameone.com/javadoc/com/codename1/ui/layouts/BorderLayout.html

410

Graphics, Drawing, Images & Fonts

411

Figure 9.12. Rotating the rectangle

Graphics, Drawing, Images & Fonts

This may not be an intuitive outcome since we drew 10 rectangle components, be we
only see a portion of one rectangle. The reason is that the rotate(angle) method

uses the screen origin as the pivot point for the rotation. Components nearer to this
pivot point will experience a less dramatic effect than components farther from it. In our
case, the rotation has caused all rectangles except the first one to be rotated outside
the bounds of their containing component - so they are being clipped. A more sensible
solution for our component would be to place the rotation pivot point somewhere inside
the component. That way all of the components would look the same. Some possibilities
would be:
Top Left Corner:
public void paint(Graphics g) {
g.setColor(0x0000ff);

g.rotate((float)(Math.PI/4.0), getAbsoluteX(),

getAbsoluteY());
g.drawRect(getX() + 5, getY() + 5, getWidth() - 10,
getHeight() - 10);
g.rotate(-(float) (Math.PI / 4.0), getAbsoluteX(),

getAbsoluteY());
}

412

Graphics, Drawing, Images & Fonts

413

Figure 9.13. Rotating the rectangle with wrong pivot point

Graphics, Drawing, Images & Fonts

Center:
public void paint(Graphics g) {
g.setColor(0x0000ff);
g.rotate(

(float)(Math.PI/4.0),

getAbsoluteX()+getWidth()/2,
getAbsoluteY()+getHeight()/2

);
g.drawRect(getX() + 5, getY() + 5, getWidth() - 10, getHeight() - 10);
g.rotate(
-(float)(Math.PI/4.0),

);

getAbsoluteX()+getWidth()/2,
getAbsoluteY()+getHeight()/2

414

Graphics, Drawing, Images & Fonts

415

Figure 9.14. Rotating the rectangle with the center pivot point

Graphics, Drawing, Images & Fonts

You could also use the Graphics.setTransform() class to apply rotations and
other complex transformations (including 3D perspective transforms), but Ill leave that
for its own topic as it is a little bit more complex.

9.10.3.Event Coordinates
The coordinate system and event handling are closely tied. You can listen for touch
events on a component by overriding the pointerPressed(x,y) method. The
coordinates received in this method will be absolute screen coordinates, so you
may need to do some conversions on these coordinates before using them in your
drawXXX() methods.
E.g. a pointerPressed() callback method can look like this:
public void pointerPressed(int x, int y) {
}

addPoint(x-getParent().getAbsoluteX(), y-getParent().getAbsoluteY());

In this case we translated these points so that they would be relative to the origin of
the parent component. This is because the drawXXX() methods for this component
take coordinates relative to the parent component.

9.11.Images
Codename One has quite a few image types: loaded, RGB (builtin), RGB
(Codename One), Mutable, EncodedImage, SVG, MultiImage, FontImage &
Timeline. There are also URLImage, FileEncodedImage, FileEncodedImageAsync,
StorageEncodedImage /Async that will be covered in the IO section.
All image types are mostly seamless to use and will just work with drawImage and
various image related image APIs for the most part with caveats on performance etc.
For animation images the code must invoke the animate()
method on the image (this is done automatically by Codename One
when placing the image as a background or as an icon!
You only need to do it if you invoke drawImage in code rather than
use a builtin component).
Performance and memory wise you should read the section below carefully and be
aware of the image types you use. The Codename One designer tries to conserve
416

Graphics, Drawing, Images & Fonts

memory and be "clever" by using only EncodedImage . While these are great for low
memory you need to understand the complexities of image locking and be aware that
you might pay a penalty if you dont.
Here are the pros/cons and logic behind every image type. This covers the logic of
how its created:

9.11.1.Loaded Image
This is the basic image you get when loading an image from the jar or
29
30
network using Image.createImage(String) , Image.createImage(InputStream)
&
31
Image.createImage(byte array,int,int) ,
Some other APIs might return this image type but those APIs do
so explicitly!
In some platforms calling getGraphics() on an image like this will throw an
exception as its immutable). This is true for almost all other images as well.
This restriction might not apply for all platforms.
The image is stored in RAM based on device logic and should be reasonably efficient
in terms of drawing speed. However, it usually takes up a lot of RAM.
To calculate the amount of RAM taken by a loaded image we use the following formula:
Image Width * Image Height * 4 = Size In RAM in Bytes

E.g. a 50x100 image will take up 20,000 bytes of RAM.

The logic behind this is simple, every pixel contains 3 color channels and an alpha
component hence 3 bytes for color and one for alpha.
This isnt the case for all images but its very common and we prefer
calculating for the worst case scenario. Even with JPEGs that dont
include an alpha channel some OSs might reuire that additional
byte.
29
https://www.codenameone.com/javadoc/com/codename1/ui/Image.html#createImage-java.lang.String30
https://www.codenameone.com/javadoc/com/codename1/ui/Image.html#createImagejava.io.InputStream31
https://www.codenameone.com/javadoc/com/codename1/ui/Image.html#createImage-byte:A-int-int-

417

Graphics, Drawing, Images & Fonts

9.11.2.The RGB Images

There are two types of RGB constructed images that are very different from one another
but since they are both technically "RGB images" we are bundling them under the
same subsection.

Internal
This is a close cousin of the loaded image. This image is created using the method
32
Image.createImage(int array, int, int) and receives the AARRGGBB data to form the
image. Its more efficient than the Codename One RGB image but cant be modified,
at least not on the pixel level.
The goal of this image type is to provide an easy way to render RGB data that
isnt modified efficiently at platform native speeds. Its technically a standard "Loaded
Image" internally.

RGBImage class
RGBImage

33

is effectively an AARRGGBB array that can be drawn by Codename One.

On most platforms this is quite inefficient but for some pixel level manipulations there
is just no other way.
An RGBImage is constructed with an int array ( int[] ) that includes
width*height elements. You can then modify the colors and alpha channel directly
within the array and draw the image to any source using standard image drawing APIs.
This is very inefficient in terms of rendering speed and memory
overhead. Only use this technique if there is absolutely no other way!

9.11.3.EncodedImage
34

EncodedImage is the workhorse of Codename One. Images returned from resource

files are EncodedImage and many APIs expect it.
The EncodedImage is effectively a loaded image that is "hidden" and extracted as
needed to remove the memory overhead associated with loaded image. When creating
32
33
34

https://www.codenameone.com/javadoc/com/codename1/ui/Image.html#createImage-int:A-int-inthttps://www.codenameone.com/javadoc/com/codename1/ui/RGBImage.html
https://www.codenameone.com/javadoc/com/codename1/ui/EncodedImage.html

418

Graphics, Drawing, Images & Fonts

an EncodedImage only the PNG (or JPEG etc.) is loaded to an array in RAM.
Normally such images are very small (relatively) so they can be kept in memory without
much overhead.
When image information is needed (pixels) the image is decoded into RAM and kept in
a weak/sort reference. This allows the image to be cached for performance and allows
the garbage collector to reclaim it when the memory becomes scarce.
Since the fully decoded image can be pretty big ( width X height X 4 ) the
ability to store just the encoded image can be pretty stark. E.g. taking our example
above a 50x100 image will take up 20,000 bytes of RAM for a loaded image but an
EncodedImage can reduce that to 1kb-2kb of RAM.
An EncodedImage might be more expensive than a loaded image
as it will take up both the encoded size and the loaded size. So the
cost might be slightly bigger in some cases. Its main value is its
ability to shrink.
When drawing an EncodedImage it checks the weak reference cache and if the
image is cached then it is shown otherwise the image is loaded the encoded image
cache it then drawn.
EncodedImage is not final and can be derived to produce complex image fetching
35
strategies e.g. the URLImage class that can dynamically download its content from
the web.
EncodedImage can be instantiated via the create methods in the EncodedImage
class. Pretty much any image can be converted into an EncodedImage via the
36
createFromImage(Image, boolean) method.

EncodedImage Locking
Naturally loading the image is more expensive so we want the images that are on
the current form to remain in cache (otherwise GC will thrash a lot). Thats where
lock() kicks in, when lock() is active we keep a hard reference to the actual
native image so it wont get GCd. This significantly improves performance!
35
36

https://www.codenameone.com/javadoc/com/codename1/ui/URLImage.html
https://www.codenameone.com/javadoc/com/codename1/ui/EncodedImage.html#createFromImage-

com.codename1.ui.Image-boolean-

419

Graphics, Drawing, Images & Fonts

Internally this is invoked automatically for background images, icons etc. which
results in a huge performance boost. This makes sense since these images
are currently showing and they will be in RAM anyway. However, if you use a
complex renderer or custom drawing UI you should lock() your images where
possible!
To verify that locking might be a problem you can launch the performance monitor
tool (accessible from the simulator menu), if you get log messages that indicate
that an unlocked image was drawn you might have a problem.

9.11.4.MultiImage
Multi images dont physically exist as a concept within the Codename One API so
there is no way to actually create them and they are in no way distinguishable from
EnclodedImage .
The only builtin support for multi images is in the resource file loading logic where a
MultiImage is decoded and only the version that matches the current DPI is physically
loaded. From that point on user code can treat it like any other EnclodedImage .
9-image borders use multi images by default to keep their appearance more refined
on the different DPIs.

9.11.5.FontImage & Material Design Icons

37

FontImage allows using an icon font as if it was an image. You can specify the
character, color and size and then treat the FontImage as if its a regular image. The
huge benefits are that the font image can adapt to platform conventions in terms of
color and easily scale to adapt to DPI.
38

You can generate icon fonts using free tools on the internet such as this . Icon fonts
are a remarkably simple and powerful technique to create a small, modern applications.
Icon fonts can be created in 2 basic ways the first is explicitly by defining all of the
elements within the font.
Form hi = new Form("Icon Font");

Font materialFont = FontImage.getMaterialDesignFont();

int w = Display.getInstance().getDisplayWidth();
37
38

https://www.codenameone.com/javadoc/com/codename1/ui/FontImage.html
http://fontello.com/

420

Graphics, Drawing, Images & Fonts

FontImage fntImage = FontImage.createFixed("\uE161",
materialFont, 0xff0000, w, w);
hi.add(fntImage);
hi.show();

Figure 9.15. Icon font from material design icons created with the
fixed size of display width
The samples use the builtin material design icon font. This is for
convenience so the sample will work out of the box, for everyone.
However you should be able to do this with any arbitrary icon font off
the internet as long as its a valid TTF file.
421

Graphics, Drawing, Images & Fonts

A more common and arguably "correct" way to construct such an icon would be thru
39
the Style object. The Style object can provide the color, size and background
information needed by FontImage .

There are two versions of this method, the first one expects the Style object to have
the correct icon font set to its font attribute. The second accepts a Font object as an
argument. The latter is useful for a case where you want to reuse the same Style
object that you defined for a general UI element e.g. we can set an icon for a Button
like this and it will take up the style of the Button :
Form hi = new Form("Icon Font");

Font materialFont = FontImage.getMaterialDesignFont();

int size = Display.getInstance().convertToPixels(6, true);

materialFont = materialFont.derive(size, Font.STYLE_PLAIN);

Button myButton = new Button("Save");

myButton.setIcon(FontImage.create("\uE161", myButton.getUnselectedStyle(),
materialFont));
hi.add(myButton);
hi.show();

Figure 9.16. An image created from the Style object

Notice that for this specific version of the method the size of the
font is used to determine the icon size. In the other methods for
FontImage creation the size of the font is ignored!

Material Design Icons

There are many icon fonts in the web, the field is rather volatile and constantly changing.
However, we wanted to have builtin icons that would allow us to create better looking
demos and builtin components.
39

https://www.codenameone.com/javadoc/com/codename1/ui/plaf/Style.html

422

Graphics, Drawing, Images & Fonts

Thats why we picked the material design icon font for inclusion in the Codename One
distribution. It features a relatively stable core set of icons, that arent IP encumbered.
You can use the builtin font directly as demonstrated above but there are far better
ways to create a material design icon. To find the icon you want you can check out the
40
material design icon gallery . E.g. we used the save icon in the samples above.
To recreate the save icon from above we can do something like:
Form hi = new Form("Icon Font");

Button myButton = new Button("Save");

myButton.setIcon(FontImage.createMaterial(FontImage.MATERIAL_SAVE,
myButton.getUnselectedStyle()));
hi.add(myButton);

Figure 9.17. Material save icon

Notice that the icon is smaller now as its calculated based on the
font size of the Button UIID.
We can even write the code in a more terse style using:
Form hi = new Form("Icon Font");

Button myButton = new Button("Save");

FontImage.setMaterialIcon(myButton, FontImage.MATERIAL_SAVE);
hi.add(myButton);

This will produce the same result for slightly shorter syntax.
FontImage can conflict with some complex APIs that expect a
"real" image underneath. Some odd issues can often be resolved
40

https://design.google.com/icons/

423

Graphics, Drawing, Images & Fonts

by using the toImage() or toEncodedImage() methods to
convert the scaled FontImage to a loaded image.

9.11.6.Timeline
Timelines allow rudimentary animation and enable GIF importing using the Codename
One Designer. Effectively a timeline is a set of images that can be moved rotated,
scaled & blended to provide interesting animation effects. It can be created manually
41
using the Timeline class.

9.11.7.Image Masking
Image masking allows us to manipulate images by changing the opacity of an
image according to a mask image. The mask image can be hardcoded or generated
dynamically, it is then converted to a Mask object that can be applied to any image.
Notice that the masking process is computationally intensive, it should be done once
and cached/saved.
The code below can convert an image to a rounded image:
Toolbar.setGlobalToolbar(true);

Form hi = new Form("Rounder", new BorderLayout());

Label picture = new Label("", "Container");

hi.add(BorderLayout.CENTER, picture);
hi.getUnselectedStyle().setBgColor(0xff0000);
hi.getUnselectedStyle().setBgTransparency(255);
Style s = UIManager.getInstance().getComponentStyle("TitleCommand");
Image camera = FontImage.createMaterial(FontImage.MATERIAL_CAMERA, s);
hi.getToolbar().addCommandToRightBar("", camera, (ev) -> {
try {

int width = Display.getInstance().getDisplayWidth();

Image capturedImage =
Image.createImage(Capture.capturePhoto(width, -1));
Image roundMask = Image.createImage(width,
capturedImage.getHeight(), 0xff000000);
Graphics gr = roundMask.getGraphics();
gr.setColor(0xffffff);
gr.fillArc(0, 0, width, width, 0, 360);
Object mask = roundMask.createMask();
capturedImage = capturedImage.applyMask(mask);
picture.setIcon(capturedImage);
hi.revalidate();
41

https://www.codenameone.com/javadoc/com/codename1/ui/animations/Timeline.html

424

Graphics, Drawing, Images & Fonts

} catch(IOException err) {

});

Log.e(err);

Figure 9.18. Picture after the capture was complete and the resulted
image was rounded. The background was set to red so the rounding
effect will be more noticeable
Notice that this example is simplistic in order to be self contained. We often recommend
that developers ship "ready made" mask images with their application which can allow
very complex effects on the images.
425

Graphics, Drawing, Images & Fonts

9.11.8.URLImage
URLImage

42

is an image created with a URL, it implicitly downloads and adapts the

image in the given URL while caching it locally. The typical adapt process scales the
image or crops it to fit into the same size which is a hard restriction because of the way
URLImage is implemented.

How Does URLImage Work?

The reason for the size restriction lies in the implementation of URLImage .
URLImage is physically an animated image and so the UI thread tries to invoke
its animate() method to refresh. The URLImage uses that call to check if
the image was fetched and if not fetches it asynchronously.
Once the image was fetched the animate() method returns true to refresh
the UI. During the loading process the placeholder is shown, the reason for
the restriction in size is that image animations cant "grow" the image. They
are assumed to be fixed so the placeholder must match the dimensions of the
resulting image.

The simple use case is pretty trivial:

Image i =
URLImage.createToStorage(placeholder, "fileNameInStorage", "http://xxx/
myurl.jpg", URLImage.RESIZE_SCALE);

Alternatively you can use the similar URLImage.createToFileSystem method

43
instead of the Storage version.
This image can now be used anywhere a regular image will appear, it will initially
show the placeholder image and then seamlessly replace it with the file after it was
downloaded and stored. Notice that if you make changes to the image itself (e.g. the
scaled method) it will generate a new image which wont be able to fetch the actual
image.
42
43

https://www.codenameone.com/javadoc/com/codename1/ui/URLImage.html
https://www.codenameone.com/javadoc/com/codename1/io/Storage.html

426

Graphics, Drawing, Images & Fonts

44

Since ImageIO is used to perform the operations of the adapter

interface its required that ImageIO will work. It is currently working

in JavaSE, Android, iOS & Windows Phone. It doesnt work on J2ME/

Blackberry devices so if you pass an adapter instance on those
platforms it will probably fail to perform its task.
If the file in the URL contains an image that is too big it will scale it to match the size
of the placeholder precisely!
There is also an option to fail if the sizes dont match. Notice that the image that will be
saved is the scaled image, this means you will have very little overhead in downloading
images that are the wrong size although you will get some artifacts.
The last argument is really quite powerful, its an interface called
45
URLImage.ImageAdapter and you can implement it to adapt the downloaded image
in any way you like. E.g. you can use an image mask to automatically create a rounded
version of the downloaded image.
To do this you can just override:
public EncodedImage adaptImage(EncodedImage downloadedImage, Image
placeholderImage)

In the adapter interface and just return the processed encoded image. If you do heavy
processing (e.g. rounded edge images) you would need to convert the processed image
back to an encoded image so it can be saved. You would then also want to indicate
that this operation should run asynchronously via the appropriate method in the class.
If you need to download the file instantly and not wait for the image to appear
before download initiates you can explicitly invoke the fetch() method which will

asynchronously fetch the image from the network. Notice that the downloading will still
take time so the placeholder is still required.

Mask Adapter
A URLImage can be created with a mask adapter to apply an effect to an image. This
allows us to round downloaded images or apply any sort of masking e.g. we can adapt
the round mask code above as such:
44
45

https://www.codenameone.com/javadoc/com/codename1/ui/util/ImageIO.html
https://www.codenameone.com/javadoc/com/codename1/ui/URLImage.ImageAdapter.html

427

Graphics, Drawing, Images & Fonts

Image roundMask = Image.createImage(placeholder.getWidth(),

placeholder.getHeight(), 0xff000000);
Graphics gr = roundMask.getGraphics();

gr.setColor(0xffffff);
gr.fillArc(0, 0, placeholder.getWidth(), placeholder.getHeight(), 0, 360);
URLImage.ImageAdapter ada = URLImage.createMaskAdapter(roundMask);
Image i =
URLImage.createToStorage(placeholder, "fileNameInStorage", "http://xxx/
myurl.jpg", ada);

URLImage In Lists
The biggest problem with image download service is with lists. We decided to
46
attack this issue at the core by integrating URLImage
support directly into
47
48
49
GenericListCellRenderer
which means it will work with MultiList , List
&
50
ContainerList . To use this support just define the name of the component (name not
UIID) to end with _URLImage and give it an icon to use as the placeholder. This is
easy to do in the multilist by changing the name of icon to icon_URLImage then using
this in the data:
map.put("icon_URLImage", urlToActualImage);

Make sure you also set a "real" icon to the entry in the GUI builder or in handcoded
applications. This is important since the icon will be implicitly extracted and used as
the placeholder value. Everything else should be handled automatically. You can use
setDefaultAdapter & setAdapter on the generic list cell renderer to install
adapters for the images. The default is a scale adapter although we might change that
to scale fill in the future.
Style s = UIManager.getInstance().getComponentStyle("Button");
FontImage p = FontImage.createMaterial(FontImage.MATERIAL_PORTRAIT, s);
EncodedImage placeholder =
EncodedImage.createFromImage(p.scaled(p.getWidth() * 3, p.getHeight()
* 4), false);
46

https://www.codenameone.com/javadoc/com/codename1/ui/URLImage.html
47
https://www.codenameone.com/javadoc/com/codename1/ui/list/GenericListCellRenderer.html
48
https://www.codenameone.com/javadoc/com/codename1/ui/list/MultiList.html
49
https://www.codenameone.com/javadoc/java/util/List.html
50
https://www.codenameone.com/javadoc/com/codename1/ui/list/ContainerList.html

428

Graphics, Drawing, Images & Fonts

Form hi = new Form("MultiList", new BorderLayout());

ArrayList<Map<String, Object>> data = new ArrayList<>();
data.add(createListEntry("A Game of Thrones", "1996", "http://
www.georgerrmartin.com/wp-content/uploads/2013/03/GOTMTI2.jpg"));
data.add(createListEntry("A Clash Of Kings", "1998", "http://
www.georgerrmartin.com/wp-content/uploads/2012/08/clashofkings.jpg"));
data.add(createListEntry("A Storm Of Swords", "2000", "http://
www.georgerrmartin.com/wp-content/uploads/2013/03/stormswordsMTI.jpg"));
data.add(createListEntry("A Feast For Crows", "2005", "http://
www.georgerrmartin.com/wp-content/uploads/2012/08/feastforcrows.jpg"));
data.add(createListEntry("A Dance With Dragons", "2011", "http://
georgerrmartin.com/gallery/art/dragons05.jpg"));
data.add(createListEntry("The Winds of Winter", "2016 (please, please,
please)", "http://www.georgerrmartin.com/wp-content/uploads/2013/03/
GOTMTI2.jpg"));
data.add(createListEntry("A Dream of Spring", "Ugh", "http://
www.georgerrmartin.com/wp-content/uploads/2013/03/GOTMTI2.jpg"));
DefaultListModel<Map<String, Object>> model = new
DefaultListModel<>(data);

MultiList ml = new MultiList(model);

ml.getUnselectedButton().setIconName("icon_URLImage");
ml.getSelectedButton().setIconName("icon_URLImage");
ml.getUnselectedButton().setIcon(placeholder);
ml.getSelectedButton().setIcon(placeholder);
hi.add(BorderLayout.CENTER, ml);

The createListEntry method then looks like this:

private Map<String, Object> createListEntry(String name, String date,
String coverURL) {

Map<String, Object> entry = new HashMap<>();

entry.put("Line1", name);
entry.put("Line2", date);
entry.put("icon_URLImage", coverURL);
entry.put("icon_URLImageName", name);

return entry;

429

Graphics, Drawing, Images & Fonts

Figure 9.19. A URL image fetched dynamically into the list model

430

Chapter10.Events
There are two layers of event handlers in Codename One :icons: font
Most events in Codename One are routed via the high level events (e.g. action listener)
but sometimes we need access to low level events (e.g. when drawing via Graphics)
that provide more fine grained access. Typically working with the higher level events is
far more potable since it might map to different functionality on different devices.

10.1.High Level Events

High level events are broadcast using an addListener / setListener - publish/
1
subscribe system. Most of them are channeled via the EventDispatcher class which
further simplifies that and makes sending events correctly far easier.
All events are fired on the Event Dispatch Thread, the
EventDispatcher makes sure of that.

10.1.1.Chain Of Events
Since all events fire on the EDT some complexities occur. E.g.:
We have two listeners monitoring the same event (or related events e.g. pointer event
and button click event both of which will fire when the button is touched).
When the event occurs we can run into a scenario like this:
1. First event fires
2. It shows a blocking dialog or invokes an "AndWait" API
3. Second event fires only after the dialog was dismissed!
This happens because events are processed in-order per cycle. Since the old EDT
cycle is stuck (because of the Dialog ) the rest of the events within the cycle cant
complete. New events are in a new EDT cycle so they can finish just fine!
A workaround to this issue is to wrap the code in a callSerially , you shouldnt do
this universally as this can create a case of shifting the problem to the next EDT cycle.
However, using callSerially will allow the current cycle to flush which should help.
1

https://www.codenameone.com/javadoc/com/codename1/ui/util/EventDispatcher.html

431

Events
Another workaround for the issue is avoiding blocking calls within an event chain.

10.1.2.Action Events
2

The most common high level event is the ActionListener which allows binding a
generic action event to pretty much anything. This is so ubiquitous in Codename One
that it is even used for networking (as a base class) and for some of the low level event
options.
3

E.g. we can bind an event callback for a Button by using:

Button b = new Button("Click Me");

b.addActionListener(new ActionListener() {

public void actionPerformed(ActionEvent ev) {

});

// button was clicked, you can do anything you want here...

Or thanks to the Java 8 lambdas we can write it as:

Button b = new Button("Click Me");
b.addActionListener((ev) ->
});

// button was clicked, you can do anything you want here...

Notice that the click will work whether the button was touched using a mouse, finger or
keypad shortcut seamlessly with an action listener. Many components work with action
events e.g. buttons, text components, slider etc.
There are quite a few types of high level event types that are more specific to
requirements.

Types Of Action Events

When an action event is fired it is given a type, however this type might change as the
event evolves e.g. a command triggered by a pointer event wont include details of the
original pointer event.
2
3

https://www.codenameone.com/javadoc/com/codename1/ui/events/ActionListener.html
https://www.codenameone.com/javadoc/com/codename1/ui/Button.html

432

Events
4

You can get the event type from getEventType() , this also gives you a rather
exhaustive list of the possible event types for the action event.

Source Of Event
ActionEvent has a source object, what that source is depends heavily on the event
type. For most component based events this is the component but there are some
nuances.
The getComponent() method might not get the actual component. In case of a lead
5
6
component such as MultiButton the underlying Button will be returned and not the
MultiButton itself.
To get the component that you would logically think of as the source component use
the getActualComponent() method.

Event Consumption
An ActionEvent can be consumed, once consumed it will no longer proceed down
the chain of event processing. This is useful for some cases where we would like to
block behavior from proceeding down the path.
E.g. the event dispatch thread allows us to listen to errors on the EDT using:
Display.getInstance().addEdtErrorHandler((e) -> {
Exception err = (Exception)e.getSource();
});

// ...

This will work great but you will still get the default error message from the EDT over
that exception. To prevent the event from proceeding to the default error handling you
can just do this:
Display.getInstance().addEdtErrorHandler((e) -> {
e.consume();
Exception err = (Exception)e.getSource();
// ...

4
5
6

https://www.codenameone.com/javadoc/com/codename1/ui/events/ActionEvent.html#getEventType-https://www.codenameone.com/javadoc/com/codename1/components/MultiButton.html
https://www.codenameone.com/javadoc/com/codename1/ui/Button.html

433

Events
});

Notice that you can check if an event was already consumed using the
isConsumed() method but its pretty unlikely that you will receive a consumed event
as the system will usually stop sending it.

NetworkEvent
7

NetworkEvent is a subclass of ActionEvent that is passed to actionPerformed

callbacks made in relation to generic network code. E.g.
NetworkManager.getInstance().addErrorListener(new
ActionListener<NetworkEvent>() {

public void actionPerformed(NetworkEvent ev) {

// now we have access to the methods on NetworkEvent that provide

more information about the network specific flags

});

Or with Java 8 lambdas:

NetworkManager.getInstance().addErrorListener((ev) -> {

// now we have access to the methods on NetworkEvent that provide more

information about the network specific flags

});

The NetworkEvent allows the networking code to reuse the EventDispatcher

infrastructure and to simplify event firing thru the EDT. But you should notice that some
code might not be equivalent e.g. we could do this to read the input stream:
ConnectionRequest r = new ConnectionRequest() {
@Override

protected void readResponse(InputStream input) throws IOException {

};

// read the input stream

or we can do something similar using this code:

7

https://www.codenameone.com/javadoc/com/codename1/io/NetworkEvent.html

434

Events

ConnectionRequest r = new ConnectionRequest();

r.addResponseListener((e) -> {

byte[] data = (byte[])e.getMetaData();

});

// work with the byte data

These seem very similar but they have one important distinction. The latter code is
invoked on the EDT, so if data is big it might slow down processing significantly.
The ConnectionRequest is invoked on the network thread and so can process any
amount of data without slowing down the UI significantly.

10.1.3.DataChangeListener
8

The DataChangedListener is used in several places to indicate that the underlying

model data has changed:
9

TextField - the text field provides an action listener but that only "fires" when the
data input is complete. DataChangeListener fires with every key entered and
thus allows functionality such as "auto complete" and is indeed used internally in
the Codename One AutoCompleteTextField.
10

11

12

TableModel & ListModel - the model for the Table class notifies the view that
its content has changed via this event, thus allowing the UI to refresh properly.
There is a very exhaustive example of search that is implemented using the
DataChangedListener in the Toolbar section.

10.1.4.FocusListener
The focus listener allows us to track the currently "selected" or focused component. Its
not as useful as it used to be in feature phones.
You can bind a focus listener to the Component itself and receive an event when it
gained focus, or you can bind the listener to the Form and receive events for every
focus change event within the hierarchy.
8

https://www.codenameone.com/javadoc/com/codename1/ui/events/DataChangedListener.html
9
https://www.codenameone.com/javadoc/com/codename1/ui/TextField.html
10
https://www.codenameone.com/javadoc/com/codename1/ui/table/TableModel.html
11
https://www.codenameone.com/javadoc/com/codename1/ui/list/ListModel.html
12
https://www.codenameone.com/javadoc/com/codename1/ui/table/Table.html

435

Events

10.1.5.ScrollListener
ScrollListener

13

allows tracking scroll events so UI elements can be adapted if

necessary.
Normally scrolling is seamless and this event isnt necessary, however if developers
wish to "shrink" or "fade" an element on scrolling this interface can be used to achieve
that. Notice that you should bind the scroll listener to the actual scrollable component
and not to an arbitrary component.
E.g. in this code from the Flickr demo the Toolbar
position:

14

is faded based on scroll

public class CustomToolbar extends Toolbar implements ScrollListener {

private int alpha;

public CustomToolbar() {
}

public void paintComponentBackground(Graphics g) {

int a = g.getAlpha();
g.setAlpha(alpha);

super.paintComponentBackground(g);
}

g.setAlpha(a);

public void scrollChanged(int scrollX, int scrollY, int

oldscrollX, int oldscrollY) {

alpha = scrollY;
alpha = Math.max(alpha, 0);
alpha = Math.min(alpha, 255);

There is a better way of implementing this exact effect using title

animations illustrated here.

13
14

https://www.codenameone.com/javadoc/com/codename1/ui/events/ScrollListener.html
https://www.codenameone.com/javadoc/com/codename1/ui/Toolbar.html

436

Events

10.1.6.SelectionListener
The SelectionListener

15

event is mostly used to broadcast list model selection changes

to the list view. Since list supports the ActionListener event callback its usually
the better option since its more coarse grained.
SelectionListener gets fired too often for events and that might result in a

performance penalty. When running on non-touch devices list selection could be

changed with the keypad and only a specific fire button click would fire the action
event, for those cases SelectionListener made a lot of sense. However, in touch
devices this API isnt as useful.

10.1.7.StyleListener
StyleListener

16

allows components to track changes to the style objects. E.g. if the

developer does something like:

cmp.getUnselectedStyle().setFgColor(0xffffff);

This will trigger a style event that will eventually lead to the component being repainted.
This is quite important for the component class but not a very important event for
general user code. It is recommended that developers dont bind a style listener.

10.1.8.Event Dispatcher
When creating your own components and objects you sometimes want to broadcast
17
your own events, for that purpose Codename One has the EventDispatcher class
which saves a lot of coding effort in this regard. E.g. if you wish to provide an
18
ActionListener event for components you can just add this to your class:
private final EventDispatcher listeners = new EventDispatcher();
public void addActionListener(ActionListener a) {
}

listeners.addListener(a);

public void removeActionListener(ActionListener a) {

15
https://www.codenameone.com/javadoc/com/codename1/ui/events/SelectionListener.html
16
https://www.codenameone.com/javadoc/com/codename1/ui/events/StyleListener.html
17
https://www.codenameone.com/javadoc/com/codename1/ui/util/EventDispatcher.html
18
https://www.codenameone.com/javadoc/com/codename1/ui/events/ActionListener.html

437

Events

listeners.removeListener(a);

Then when you need to broadcast the event just use:

private void fireEvent(ActionEvent ev) {
}

listeners.fireActionEvent(ev);

10.2.Low Level Events

Low level events map to "system" events directly. Touch events are considered low
level since they might expose platform specific nuances to your code.
E.g. one platform might send a very large number of events during drag while another
might send only a few. Normally the high level event handling hides those complexities
but some of them trickle down into the low level event handling.
Codename One tries to hide some of the complexities from the low
level events as well. However, due to the nature of the event types
its a more challenging task.
Low level events can be bound in one of 3 ways:
Use
one
of
the
add
listener
addPointerPressedListener .

methods

Override one of the event callbacks on Form

Override one of the event callbacks on a Component

20

in

Form

19

e.g.

When you override event callbacks on a Component the

Component in question must be focusable and have focus at that
point. This can be an advantage for some use cases as it will save
you the need of handling unrelated events.
Each of those has advantages and disadvantages, specifically:
'Form' based events and callbacks deliver pointer events in the 'Form' coordinate
space.
19
20

https://www.codenameone.com/javadoc/com/codename1/ui/Form.html
https://www.codenameone.com/javadoc/com/codename1/ui/Component.html

438

Events
'Component' based events require focus
'Form' based events can block existing functionality from proceeding thru the event
chain e.g. you can avoid calling super in a form event and thus block other events
from happening (e.g. block a listener or component event from triggering).

Table 10.1. Event type map

Listener

Override Form

Override
Component

Coordinate System Form

Form

Component

Block current
functionality

Partially (event
consume)

No

Yes, just avoid

super

10.2.1.Low Level Event Types

There are two basic types of low level events: Key and Pointer.
Key events are only relevant to physical keys and will not trigger
21
on virtual keyboard keys, to track those use a TextField with a
DataChangeListener as mentioned above.
The pointer events (touch events) can be intercepted by overriding one or more of these
methods in Component or Form . Notice that unless you want to block functionality
you should probably invoke super when overriding:
public void pointerDragged(int[] x, int[] y)

public void pointerDragged(final int x, final int y)

public void pointerPressed(int[] x, int[] y)
public void pointerPressed(int x, int y)

public void pointerReleased(int[] x, int[] y)

public void pointerReleased(int x, int y)

public void longPointerPress(int x, int y)

public void keyPressed(int keyCode)

public void keyReleased(int keyCode)

public void keyRepeated(int keyCode)

Notice that most pointer events have a version that accepts an array as an argument,
this allows for multi-touch event handling by sending all the currently touched
coordinates.
21

https://www.codenameone.com/javadoc/com/codename1/ui/TextField.html

439

Events

10.2.2.Drag Event Sanitation

Drag events are quite difficult to handle properly across devices. Some devices send
a ridiculous number of events for even the lightest touch while others send too little.
It seems like too many drag events wouldnt be a problem, however if we drag over
a button then it might disable the buttons action event (since this might be the user
trying to scroll).
Drag sensitivity is really about the component being dragged which is why we have the
method getDragRegionStatus that allows us to "hint" to the drag API whether we
are interested in drag events or not and if so in which directional bias.
E.g. if our component is a painting app where we are trying to draw using drag gestures
we would use code such as:
public class MyComponent extends Component {

protected int getDragRegionStatus(int x, int y) {

return DRAG_REGION_LIKELY_DRAG_XY;

This indicates that we want all drag events on both AXIS to be sent as soon as possible.
Notice that this doesnt completely disable event sanitation.

10.3.BrowserNavigationCallback
The BrowserNavigationCallback
classification for it.

22

isnt quite an "event" but there is no real "proper"

The callback method of this interface is invoked off the EDT!

You must NEVER block this method and must not access UI or
Codename One sensitive elements in this method!
The browser navigation callback is invoked directly from the native web component as
it navigates to a new page. Because of that it is invoked on the native OS thread and
gives us a unique opportunity to handle the navigation ourselves as we see fit. That
is why it MUST be invoked on the native thread, since the native browser is pending
on our response to that method, spanning an invokeAndBlock/callSerially would be to
slow and would bog down the browser.
22

https://www.codenameone.com/javadoc/com/codename1/ui/events/BrowserNavigationCallback.html

440

Events
You can use the browser navigation callback to change the UI or even to invoke Java
code from JavaScript code e.g.:
bc.setBrowserNavigationCallback((url) -> {
if(url.startsWith("http://click")) {

Display.getInstance().callSerially(() -> bc.execute("fnc('<p>You

clicked!</p>')"));
}
});

return false;

return true;

441

Chapter11.File System, Storage,

Network & Parsing
In this chapter we cover the IO frameworks, which include everything from network to
storage, filesystem and parsing :icons: font

11.1.Jar Resources
Resources that are packaged within the "JAR" dont really belong in this
section of the developer guide but since they are often confused with
Storage / FileSystemStorage this might be the best place to clarify what they are.
You can place arbitrary files within the src directory of a Codename One project. This
file will get packaged into the final distribution. In standard Java SE you can usually
do something like:
InputStream i = getClass().getResourceAsStream("/myFile");

This isnt guaranteed to work on all platforms and will probably fail on some. Instead
you should use something such as:
InputStream i = Display.getInstance().getResourceAsStream(getClass(), "/
myFile");

This isnt the only limitation though, you can use hierarchies so something like this
would fail:
InputStream i = Display.getInstance().getResourceAsStream(getClass(), "/
res/myFile");

You cant use relative paths either so this will fail as well (notice the lack of the first
slash):
InputStream i =
Display.getInstance().getResourceAsStream(getClass(), "myFile");

The reason for those limitations is portability, on iOS and Android resources behave
quite differently so supporting the full Java SE semantics is unrealistic.
442

File System, Storage, Network & Parsing

This is even worse in some regards. Because of the way iOS works
with resources some unique file names might fail e.g. if you use the
@ character or have a . more than once (e.g. file.ext.act )
Notice that just like in Java SE, the entries within the "JAR" are read only and cant be
modified. You cant gain access to the actual file, only to the stream!

11.2.Storage
1

Storage is accessed via the Storage class. It is a flat filesystem like interface and
contains the ability to list/delete and write to named storage entries.
The Storage API also provides convenient methods to write objects to Storage
and read them from Storage specifically readObject & writeObject .
The object in Storage are deleted when an app is uninstalled but
are retained between application updates.
The sample code below demonstrates listing the content of the storage, adding/viewing
and deleting entries within the storage:
Toolbar.setGlobalToolbar(true);

Form hi = new Form("Storage", new BoxLayout(BoxLayout.Y_AXIS));

hi.getToolbar().addCommandToRightBar("+", null, (e) -> {

TextField tf = new TextField("", "File Name", 20, TextField.ANY);

TextArea body = new TextArea(5, 20);
body.setHint("File Body");

Command ok = new Command("OK");

Command cancel = new Command("Cancel");

Command result = Dialog.show("File Name",

BorderLayout.north(tf).add(BorderLayout.CENTER, body), ok, cancel);
if(ok == result) {

try(OutputStream os =

Storage.getInstance().createOutputStream(tf.getText())) {
os.write(body.getText().getBytes("UTF-8"));
createFileEntry(hi, tf.getText());
hi.getContentPane().animateLayout(250);
} catch(IOException err) {

}
1

Log.e(err);

https://www.codenameone.com/javadoc/com/codename1/io/Storage.html

443

File System, Storage, Network & Parsing

});
for(String file : Storage.getInstance().listEntries()) {
createFileEntry(hi, file);

}
hi.show();

private void createFileEntry(Form hi, String file) {

Label fileField = new Label(file);
Button delete = new Button();
Button view = new Button();

FontImage.setMaterialIcon(delete, FontImage.MATERIAL_DELETE);
FontImage.setMaterialIcon(view, FontImage.MATERIAL_OPEN_IN_NEW);
Container content = BorderLayout.center(fileField);
int size = Storage.getInstance().entrySize(file);

content.add(BorderLayout.EAST, BoxLayout.encloseX(new Label(size

+ "bytes"), delete, view));

delete.addActionListener((e) -> {
Storage.getInstance().deleteStorageFile(file);
content.setY(hi.getWidth());
hi.getContentPane().animateUnlayoutAndWait(150, 255);
hi.removeComponent(content);
hi.getContentPane().animateLayout(150);
});
view.addActionListener((e) -> {
{

try(InputStream is = Storage.getInstance().createInputStream(file))
String s = Util.readToString(is, "UTF-8");
Dialog.show(file, s, "OK", null);

} catch(IOException err) {
}

Log.e(err);

});
hi.add(content);

444

File System, Storage, Network & Parsing

Figure 11.1. List of files within the storage

445

File System, Storage, Network & Parsing

Figure 11.2. Content of a file added to the storage

11.2.1.The Preferences API

2

Storage also offers a very simple API in the form of the Preferences class. The
Preferences class allows developers to store simple variables, strings, numbers,
booleans etc. in storage without writing any storage code. This is a common use case
within applications e.g. you have a server token that you need to store you can store
it like this:
2

https://www.codenameone.com/javadoc/com/codename1/io/Preferences.html

446

File System, Storage, Network & Parsing

Preferences.set("token", myToken);

You can then read the token like this:

String token = Preferences.get("token", null);

This gets somewhat confusing with primitive numbers e.g.

if you use Preferences.set("primitiveLongValue",
myLongNumber)
then
invoke
Preferences.get("primitiveLongValue", 0) you might
get an exception!
This would happen because the value is physically a
Long object but you are trying to get an Integer . The
workaround is to remain consistent and use code like this
Preferences.get("primitiveLongValue", (long)0) .

11.3.File System
3

FileSystemStorage provides file system access. It maps to the underlying OSs

file system API providing most of the common operations expected from a file API
somewhat in the vain of java.io.File & java.io.FileInputStream e.g.
opening, renaming, deleting etc.
Notice that the file system API is somewhat platform specific in its behavior. All paths
used the API should be absolute otherwise they are not guaranteed to work.
The main reason

java.io.File

&

java.io.FileInputStream

werent

supported directly has a lot to do with the richness of those two APIs. They effectively
allow saving a file anywhere, however mobile devices are far more restrictive and dont
allow apps to see/modify files that are owned by other apps.

11.3.1.File Paths & App Home

All paths in FileSystemStorage are absolute, this simplifies the issue of portability
significantly since the concept of relativity and current working directory arent very
portable.
3

https://www.codenameone.com/javadoc/com/codename1/io/FileSystemStorage.html

447

File System, Storage, Network & Parsing

All URLs use the / as their path separator we try to enforce this behavior even in
Windows.
Directories end with the / character and thus can be easily distinguished by their
name.
The FileSystemStorage API provides a getRoots() call to list the root
directories of the file system (you can then "dig in" via the listFiles API). However,
this is confusing and unintuitive for developers.

To simplify the process of creating/reading files we added the getAppHomePath()

method. This method allows us to obtain the path to a directory where files can be
stored/read.
We can use this directory to place an image to share as we did in the share sample.
A common Android hack is to write files to the SDCard storage to
share them among apps. Android 4.x disabled the ability to write
to arbitrary directories on the SDCard even when the appropriate
permission was requested.
A more advanced usage of the
FileSystemStorage Tree :

FileSystemStorage

API can be a

Form hi = new Form("FileSystemTree", new BorderLayout());

TreeModel tm = new TreeModel() {
@Override

public Vector getChildren(Object parent) {

String[] files;

if(parent == null) {

files = FileSystemStorage.getInstance().getRoots();
return new Vector<Object>(Arrays.asList(files));

} else {

try {

files =
FileSystemStorage.getInstance().listFiles((String)parent);
} catch(IOException err) {
Log.e(err);

files = new String[0];

}
}
String p = (String)parent;

Vector result = new Vector();

for(String s : files) {

448

File System, Storage, Network & Parsing

}
}

result.add(p + s);

return result;

@Override

public boolean isLeaf(Object node) {

};

return !FileSystemStorage.getInstance().isDirectory((String)node);

Tree t = new Tree(tm) {

@Override

protected String childToDisplayLabel(Object child) {

String n = (String)child;

int pos = n.lastIndexOf("/");

if(pos < 0) {
}
}

return n;

return n.substring(pos);

};
hi.add(BorderLayout.CENTER, t);
hi.show();

449

File System, Storage, Network & Parsing

Figure 11.3. Simple sample of a tree for the FileSystemStorage API

11.3.2.Storage vs. File System

The question of storage vs. file system is often confusing for novice mobile developers.
This embeds two separate questions:
Why are there 2 APIs where one would have worked?
Which one should I pick?
The main reasons for the 2 APIs are technical. Many OSs provide 2 ways of
accessing data specific to the app and this is reflected within the API. E.g. on Android
450

File System, Storage, Network & Parsing

the FileSystemStorage maps to APIs such as java.io.FileInputStream
whereas the Storage maps to Context.openFileInput() .
The secondary reason for the two APIs is conceptual. FileSystemStorage is more
powerful and in a sense provides more ways to fail, this is compounded by the complex
on-device behavior of the API. Storage is designed to be friendlier to the uninitiated
and more portable.
You should pick Storage unless you have a specific requirement that prevents it.
Some APIs such as Capture expect a FileSystemStorage URI so in those
cases this would also be a requirement.
Another case where FileSystemStorage is beneficial is the case of hierarchy or
native API usage. If you need a a directory structure or need to communicate with a
native API the FileSystemStorage approach is usually easier.
In some OSs the FileSystemStorage API can find the content
of the Storage API. As one is implemented on top of the other.
This is undocumented behavior that can change at any moment!
To summarize the differences between the 3 file storage options:

Table 11.1. Compare Storage, FileSystem & Jar Resources

Option

Storage

File System

JAR Resource

Main Use Case

General application Low level access

Data

Ship data within the

app

Initial State

Blank

Blank

As defined by
developer

Modifiable

Yes

Yes

No

Supports
Hierarchies

No

Yes

No

11.4.SQL
Most new devices contain one version of sqlite or another; sqlite is a very lightweight
SQL database designed for embedding into devices. For portability we recommend
avoiding SQL altogether since it is both fragmented between devices (different sqlite
versions) and isnt supported on all devices.
In general SQL seems overly complex for most embedded device programming tasks.
451

File System, Storage, Network & Parsing

Portability Of SQLite
SQLite is supported on iOS, Android, RIM, Desktop & JavaScript builds.
However, the JavaScript version of SQL has been deprecated and isnt
supported on all platforms.
You will notice that at this time support is still missing from the Windows builds.
The biggest issue with SQLite portability is in iOS. The SQLite version for most
platforms is threadsafe and as a result very stable. However, the iOS version
is not!
This might not seem like a big deal normally, however if you forget to close a
connection the GC might close it for you thus producing a crash. This is such a
common occurrence that Codename One logs a warning when the GC collects
a database resource on the simulator.
SQL is pretty powerful and very well suited for common tabular data. The Codename
One SQL API is similar in spirit to JDBC but considerably simpler since many of the
abstractions of JDBC designed for pluggable database architecture make no sense for
a local database.
4

The Database API is a high level abstraction that allows you to open an arbitrary
database file using syntax such as:
Database db = Display.getInstance().openOrCreate(databaseName);

Some SQLite apps ship with a "ready made" database. We allow you to replace the
DB file by using the code:
String path = Display.getInstance().getDatabasePath(databaseName);

You can then use the FileSystemStorage class to write the content of your DB file
into the path. Notice that it must be a valid SQLite file!
This is very useful for applications that need to synchronize with a central server or
applications that ship with a large database as part of their core product.
4

https://www.codenameone.com/javadoc/com/codename1/db/Database.html

452

File System, Storage, Network & Parsing

Working with a database is pretty trivial, the application logic below can send arbitrary
queries to the database and present the results in a Table . You can probably integrate
this code into your app as a debugging tool:

Toolbar.setGlobalToolbar(true);
Style s = UIManager.getInstance().getComponentStyle("TitleCommand");
FontImage icon =
FontImage.createMaterial(FontImage.MATERIAL_QUERY_BUILDER, s);

Form hi = new Form("SQL Explorer", new BorderLayout());

hi.getToolbar().addCommandToRightBar("", icon, (e) -> {
TextArea query = new TextArea(3, 80);
Command ok = new Command("Execute");

Command cancel = new Command("Cancel");

if(Dialog.show("Query", query, ok, cancel) == ok) {

Database db = null;
Cursor cur = null;
try {

db = Display.getInstance().openOrCreate("MyDB.db");
if(query.getText().startsWith("select")) {

cur = db.executeQuery(query.getText());
int columns = cur.getColumnCount();
hi.removeAll();

if(columns > 0) {

boolean next = cur.next();

if(next) {

ArrayList<String[]> data = new ArrayList<>();

String[] columnNames = new String[columns];

for(int iter = 0 ; iter < columns ; iter++) {

}

columnNames[iter] = cur.getColumnName(iter);

while(next) {

Row currentRow = cur.getRow();

String[] currentRowArray = new

String[columns];

for(int iter = 0 ; iter < columns ; iter++) {

currentRow.getString(iter);

currentRowArray[iter] =

}
data.add(currentRowArray);
next = cur.next();

Object[][] arr = new Object[data.size()][];

data.toArray(arr);

hi.add(BorderLayout.CENTER, new Table(new

DefaultTableModel(columnNames, arr)));

453

File System, Storage, Network & Parsing

} else {

hi.add(BorderLayout.CENTER, "Query returned no

results");

} else {
results");

hi.add(BorderLayout.CENTER, "Query returned no

} else {

db.execute(query.getText());
hi.add(BorderLayout.CENTER, "Query completed

successfully");
}
hi.revalidate();

} catch(IOException err) {
Log.e(err);
hi.removeAll();

hi.add(BorderLayout.CENTER, "Error: " + err);

hi.revalidate();

} finally {

Util.cleanup(db);
Util.cleanup(cur);

});
hi.show();

454

File System, Storage, Network & Parsing

Figure 11.4. Querying the temp demo generated by the SQLDemo

application

455

File System, Storage, Network & Parsing

Figure 11.5. Issuing a query

11.5.Network Manager & Connection Request

One of the more common problems in Network programming is spawning a new thread
to handle the network operations. In Codename One this is done seamlessly and
5
becomes unessential thanks to the NetworkManager .
NetworkManager effectively alleviates the need for managing network threads by
managing the complexity of network threading. The connection request class can be
5

http://www.codenameone.com/javadoc/com/codename1/io/NetworkManager.html

456

File System, Storage, Network & Parsing

used to facilitate web service requests when coupled with the JSON/XML parsing
capabilities.
6

To open a connection one needs to use a ConnectionRequest object, which has some
similarities to the networking mechanism in JavaScript but is obviously somewhat more
elaborate.
You can send a get request to a URL using something like:
ConnectionRequest request = new ConnectionRequest(url, false);
request.addResponseListener((e) -> {
// process the response

});

// request will be handled asynchronously

NetworkManager.getInstance().addToQueue(request);

Notice that you can also implement the same thing and much more by
avoiding the response listener code and instead overriding the methods of the
ConnectionRequest class which offers multiple points to override e.g.
ConnectionRequest request = new ConnectionRequest(url, false) {
protected void readResponse(InputStream input) {
}

// just read from the response input stream

protected void postResponse() {

// invoked on the EDT after processing is complete to allow the

networking code
}

// to update the UI

protected void buildRequestBody(OutputStream os) {

// writes post data, by default this just works but if you want

to write this

// manually then override this

}
};
NetworkManager.getInstance().addToQueue(request);

http://www.codenameone.com/javadoc/com/codename1/io/ConnectionRequest.html

457

File System, Storage, Network & Parsing

Notice that overriding buildRequestBody(OutputStream) will
only work for POST requests and will replace writing the arguments
You dont need to close the output/input streams passed to the
request methods. They are implicitly cleaned up.
NetworkManager also supports synchronous requests which work in a similar way
7
to Dialog via the invokeAndBlock call and thus dont block the EDT illegally.
E.g. you can do something like this:
ConnectionRequest request = new ConnectionRequest(url, false);
// request will be handled synchronously

NetworkManager.getInstance().addToQueueAndWait(request);
byte[] resultOfRequest = request.getData();

Notice that in this case the addToQueueAndWait method returned after the
connection completed. Also notice that this was totally legal to do on the EDT!

11.5.1.Threading
By default the NetworkManager launches with a single network thread. This is
sufficient for very simple applications that dont do too much networking but if you need
to fetch many images concurrently and perform web services in parallel this might be
an issue.
Once you increase the thread count there is no guarantee of order for
your requests. Requests might not execute in the order with which
you added them to the queue!
To update the number of threads use:
NetworkManager.getInstance().updateThreadCount(4);

All the callbacks in the ConnectionRequest occur on the network thread and not
on the EDT!
There is one exception to this rule which is the postResponse() method designed
to update the UI after the networking code completes.
7

Event Dispatch Thread

458

File System, Storage, Network & Parsing

Never change the UI from a ConnectionRequest callback.
You can either use a listener on the ConnectionRequest , use

postResponse() (which is the only exception to this rule) or wrap

your UI code with callSerially .

11.5.2.Arguments, Headers & Methods

HTTP/S is a complex protocol that expects complex encoded data for its requests.
Codename One tries to simplify and abstract most of these complexities behind
common sense APIs while still providing the full low level access you would expect
from such an API.

Arguments
HTTP supports several "request methods", most commonly GET & POST but also a
few others such as HEAD , PUT , DELETE etc.

Arguments in HTTP are passed differently between GET and POST methods. That is
what the setPost method in Codename One determines, whether arguments added
to the request should be placed using the GET semantics or the POST semantics.
So if we continue our example from above we can do something like this:
ConnectionRequest request = new ConnectionRequest(url, false);
request.addArgument("MyArgName", value);

This will implicitly add a get argument with the content of value . Notice that we dont
really care what value is. Its implicitly HTTP encoded based on the get/post semantics.
In this case it will use the get encoding since we passed false to the constructor.
A simpler implementation could do something like this:
ConnectionRequest request = new ConnectionRequest(url +
"MyArgName=" + Util.encodeUrl(value), false);

This would be almost identical but doesnt provide the convenience for switching back
and forth between GET / POST and it isnt as fluent.
We can skip the encoding in complex cases where server code expects illegal HTTP
characters (this happens) using the addArgumentNoEncoding method. We can
also add multiple arguments with the same key using addArgumentArray .
459

File System, Storage, Network & Parsing

Methods
As we explained above, the setPost() method allows us to manipulate the get/post
semantics of a request. This implicitly changes the POST or GET method submitted
to the server.
However, if you wish to have finer grained control over the submission process e.g. for
making a HEAD request you can do this with code like:
ConnectionRequest request = new ConnectionRequest(url, false);
request.setHttpMethod("HEAD");

Headers
When communicating with HTTP servers we often pass data within headers mostly for
authentication/authorization but also to convey various properties.
Some headers are builtin as direct APIs e.g. content type is directly exposed within
the API since its a pretty common use case. We can set the content type of a post
request using:
ConnectionRequest request = new ConnectionRequest(url, true);
request.setContentType("text/xml");

We can also add any arbitrary header type we want, e.g. a very common use case is
basic authorization where the authorization header includes the Base64 encoded user/
password combination as such:
String authCode = user + ":" + password;
String authHeader = "Basic " + Base64.encode(authCode.getBytes());
request.addRequestHeader("Authorization", authHeader);

This can be quite tedious to do if you want all requests from your app to use this header.
For this use case you can just use:
String authCode = user + ":" + password;
String authHeader = "Basic " + Base64.encode(authCode.getBytes());
NetworkManager.getInstance().addDefaultHeader("Authorization",
authHeader);

460

File System, Storage, Network & Parsing

Server Headers
Server returned headers are a bit trickier to read. We need to subclass the connection
request and override the readHeaders method e.g.:
ConnectionRequest request = new ConnectionRequest(url, false) {

protected void readHeaders(Object connection) throws IOException {

String[] headerNames = getHeaderFieldNames(connection);
for(String headerName : headerNames) {

String headerValue = getHeader(headerName);

//....

protected void readResponse(InputStream input) {

// just read from the response input stream

}
};
NetworkManager.getInstance().addToQueue(request);

Here we can extract the headers one by one to handle complex headers such as
cookies, authentication etc.

Error Handling
As you noticed above practically all of the methods in the ConectionRequest throw
IOException . This allows you to avoid the try / catch semantics and just let the
error propagate up the chain so it can be handled uniformly by the application.
There are two distinct placed where you can handle a networking error:
The ConnectionRequest - by overriding callback methods
The NetworkManager error handler
Notice that the NetworkManager error handler takes precedence thus allowing you
to define a global policy for network error handling by consuming errors.
E.g. if I would like to block all network errors from showing anything to the user I could
do something like this:
NetworkManager.getInstance().addToQueue(request);
NetworkManager.getInstance().addErrorListener((e) -> e.consume());

461

File System, Storage, Network & Parsing

8

The error listener is invoked first with the NetworkEvent matching the error.
Consuming the event prevents it from propagating further down the chain into the
ConnectionRequest callbacks.
We can also override the error callbacks of the various types in the request e.g. in the
case of a server error code we can do:
ConnectionRequest request = new ConnectionRequest(url, false) {

protected void handleErrorResponseCode(int code, String message) {

if(code == 444) {

// do something

protected void readResponse(InputStream input) {

// just read from the response input stream

}
};
NetworkManager.getInstance().addToQueue(request);

The error callback callback is triggered in the network thread!

As a result it cant access the UI to show a Dialog or anything
like that.
Another approach is to use the setFailSilently(true) method on the
ConnectionRequest . This will prevent the ConnectionRequest from displaying
any errors to the user. Its a very powerful strategy if you use the synchronous version
of the APIs e.g.:
ConnectionRequest request = new ConnectionRequest(url, false);
request.setFailSilently(true);

NetworkManager.getInstance().addToQueueAndWait(request);
if(request.getResponseCode() != 200) {
}

// probably an error...

This code will only work with the synchronous "AndWait" version of
the method since the response code will take a while to return for
the non-wait version.
8

https://www.codenameone.com/javadoc/com/codename1/io/NetworkEvent.html

462

File System, Storage, Network & Parsing

Error Stream
When we get an error code that isnt 200/300 we ignore the result. This is problematic
as the result might contain information we need. E.g. many webservices provide further
XML/JSON based details describing the reason for the error code.
Calling setReadResponseForErrors(true) will trigger a mode where even
errors will receive the readResponse callback with the error stream. This also means
that APIs like getData and the listener APIs will also work correctly in case of error.

11.5.3.GZIP
Gzip is a very common compression format based on the lz algorithm, its used by web
servers around the world to compress data.
9

10

Codename One supports GZipInputStream and GZipOutputStream , which allow

you to compress data seamlessly into a stream and extract compressed data from a
stream. This is very useful and can be applied to every arbitrary stream.
11

Codename One also features a GZConnectionRequest , which will automatically

unzip an HTTP response if it is indeed gzipped. Notice that some devices (iOS) always
request gziped data and always decompress it for us, however in the case of iOS it
doesnt remove the gziped header. The GZConnectionRequest is aware of such
behaviors so its better to use that when connecting to the network (if applicable).
By default GZConnectionRequest doesnt request gzipped data (only unzips it
when its received) but its pretty easy to do so just add the HTTP header AcceptEncoding: gzip e.g.:
GZConnectionRequest con = new GZConnectionRequest();
con.addRequestHeader("Accept-Encoding", "gzip");

Do the rest as usual and you should have smaller responses from the servers.

https://www.codenameone.com/javadoc/com/codename1/io/gzip/GZIPInputStream.html
10
https://www.codenameone.com/javadoc/com/codename1/io/gzip/GZIPOutputStream.html
11
https://www.codenameone.com/javadoc/com/codename1/io/gzip/GZConnectionRequest.html

463

File System, Storage, Network & Parsing

11.5.4.File Upload
MultipartRequest

12

tries to simplify the process of uploading a file from the local device

to a remote server.
You can always submit data in the buildRequestBody but this is flaky and has some
limitations in terms of devices/size allowed. HTTP standardized file upload capabilities
thru the multipart request protocol, this is implemented by countless servers and is well
documented. Codename One supports this out of the box:
MultipartRequest request = new MultipartRequest();

request.setUrl(url);
request.addData("myFileName", fullPathToFile, "text/plain")
NetworkManager.getInstance().addToQueue(request);

MultipartRequest is a ConnectionRequest most stuff you

expect from there should work. Even addArgument etc.
Since we assume most developers reading this will be familiar with Java here is the
way to implement the multipart upload in the servlet API:
@WebServlet(name = "UploadServlet", urlPatterns = {"/upload"})
@MultipartConfig(fileSizeThreshold = 1024 * 1024 * 100, // 10 MB
maxFileSize = 1024 * 1024 * 150, // 50 MB
maxRequestSize = 1024 * 1024 * 200)

public class UploadServlet extends HttpServlet {

// 100 MB

@Override

public void doPost(HttpServletRequest req, HttpServletResponse res)

throws ServletException, IOException {

Collection<Part> parts = req.getParts();

Part data = parts.iterator().next();

try(InputStream is = data.getInputStream()) {}

12

// store or do something with the input stream

https://www.codenameone.com/javadoc/com/codename1/io/MultipartRequest.html

464

File System, Storage, Network & Parsing

11.5.5.Parsing
Codename One has several built in parsers for JSON, XML, CSV & Properties formats.
You can use those parsers to read data from the Internet or data that is shipping with
your product. E.g. use the CSV data to setup default values for your application.
All our parsers are designed with simplicity and small distribution size; they dont
validate and will fail in odd ways when faced with broken data. The main logic behind
this is that validation takes up CPU time on the device where CPU is a precious
resource.

Parsing CSV
CSV is probably the easiest to use, the "Comma Separated Values" format is just a list
of values separated by commas (or some other character) with new lines to indicate
another row in the table. These usually map well to an Excel spreadsheet or database
table and are supported by default in all spreadsheets.
To parse a CSV just use the CSVParser

13

class as such:

Form hi = new Form("CSV Parsing", new BorderLayout());

CSVParser parser = new CSVParser();

try(Reader r = new CharArrayReader("1997,Ford,E350,\"Super, \"\"luxurious

\"\" truck\"".toCharArray())) {
String[][] data = parser.parse(r);

String[] columnNames = new String[data[0].length];

for(int iter=
}

0 ; iter < columnNames.length ; iter++) {

columnNames[iter] = "Col " + (iter + 1);

TableModel tm = new DefaultTableModel(columnNames, data);

hi.add(BorderLayout.CENTER, new Table(tm));

} catch(IOException err) {
Log.e(err);

}
hi.show();

13

https://www.codenameone.com/javadoc/com/codename1/io/CSVParser.html

465

File System, Storage, Network & Parsing

Figure 11.6. CSV parsing results, notice the properly escaped

parentheses and comma
The data contains a two dimensional array of the CSV content. You can change the
delimiter character by using the CSVParser constructor that accepts a character.
Notice

that

we

used

CharArrayReader

from

the

com.codename1.io package for this sample. Normally you would

want to use java.util.InputStreamReader for real world
data.

JSON
The JSON ("Java Script Object Notation") format is popular on the web for passing
values to/from webservices since it works so well with JavaScript. Parsing JSON is just
14
as easy but has two different variations. You can use the JSONParser class to build
a tree of the JSON data as such:
JSONParser parser = new JSONParser();

Hashtable response = parser.parse(reader);

The response is a Map containing a nested hierarchy of Collection

( java.util.List ), Strings and numbers to represent the content of the submitted
JSON. To extract the data from a specific path just iterate the Map keys and recurs
into it.
15

The sample below uses results from an API of ice and fire that queries structured data
about the "Song Of Ice & Fire" book series. Here is a sample result returned from the API
for the query http://www.anapioficeandfire.com/api/characters?page=5&pageSize=3 :
14
15

https://www.codenameone.com/javadoc/com/codename1/io/JSONParser.html
https://anapioficeandfire.com/

466

File System, Storage, Network & Parsing

"url": "http://www.anapioficeandfire.com/api/characters/13",
"name": "Chayle",
"culture": "",
"born": "",
"died": "In 299 AC, at Winterfell",
"titles": [
"Septon"
],
"aliases": [],
"father": "",
"mother": "",
"spouse": "",
"allegiances": [],
"books": [

"http://www.anapioficeandfire.com/api/books/1",
"http://www.anapioficeandfire.com/api/books/2",
"http://www.anapioficeandfire.com/api/books/3"

],
"povBooks": [],
"tvSeries": [],
"playedBy": []

},
{

"url": "http://www.anapioficeandfire.com/api/characters/14",
"name": "Gillam",
"culture": "",
"born": "",
"died": "",
"titles": [
"Brother"
],
"aliases": [],
"father": "",
"mother": "",
"spouse": "",
"allegiances": [],
"books": [
"http://www.anapioficeandfire.com/api/books/5"
],
"povBooks": [],
"tvSeries": [],
"playedBy": []

},

467

File System, Storage, Network & Parsing

{

"url": "http://www.anapioficeandfire.com/api/characters/15",
"name": "High Septon",
"culture": "",
"born": "",
"died": "",
"titles": [
"High Septon",
"His High Holiness",
"Father of the Faithful",
"Voice of the Seven on Earth"
],
"aliases": [
"The High Sparrow"
],
"father": "",
"mother": "",

"spouse": "",
"allegiances": [],
"books": [
"http://www.anapioficeandfire.com/api/books/5",
"http://www.anapioficeandfire.com/api/books/8"
],
"povBooks": [],
"tvSeries": [
"Season 5"
],
"playedBy": [
"Jonathan Pryce"
]

We will place that into a file named "anapioficeandfire.json" in the src directory to make
the next sample simpler:
Form hi = new Form("JSON Parsing", new BoxLayout(BoxLayout.Y_AXIS));
JSONParser json = new JSONParser();
try(Reader r = new

InputStreamReader(Display.getInstance().getResourceAsStream(getClass(), "/
anapioficeandfire.json"), "UTF-8")) {
Map<String, Object> data = json.parseJSON(r);
java.util.List<Map<String, Object>> content =
(java.util.List<Map<String, Object>>)data.get("root");
for(Map<String, Object> obj : content) {

468

File System, Storage, Network & Parsing

String url = (String)obj.get("url");

String name = (String)obj.get("name");

java.util.List<String> titles =
(java.util.List<String>)obj.get("titles");

if(name == null || name.length() == 0) {

java.util.List<String> aliases =
(java.util.List<String>)obj.get("aliases");

if(aliases != null && aliases.size() > 0) {

name = aliases.get(0);

MultiButton mb = new MultiButton(name);

if(titles != null && titles.size() > 0) {

mb.setTextLine2(titles.get(0));
}
mb.addActionListener((e) -> Display.getInstance().execute(url));
hi.add(mb);

} catch(IOException err) {
Log.e(err);

}
hi.show();

The JSONParser returns a Map which is great if the root object is a Map but
in some cases its a list of elements (as is the case above). In this case a special
case "root" element is created to contain the actual list of elements.
We rely that the entries are all maps, this might not be the case for every API type.
Notice that the "titles" and "aliases" entries are both lists of elements. We use
java.util.List to avoid a clash with com.codename1.ui.List .

469

File System, Storage, Network & Parsing

Figure 11.7. Parsed JSON result, clicking the elements opens the
URL from the JSON
The structure of the returned map is sometimes unintuitive when
looking at the raw JSON. The easiest thing to do is set a breakpoint
on the method and use the inspect variables capability of your IDE
to inspect the returned element hierarchy while writing the code to
extract that data
An alternative approach is to use the static data parse() method of the JSONParser
class and implement a callback parser e.g.:

470

File System, Storage, Network & Parsing

JSONParser.parse(reader, callback);
Notice that a static version of the method is used! The callback object is an instance
of the JSONParseCallback interface, which includes multiple methods. These

methods are invoked by the parser to indicate internal parser states, this is similar to
the way traditional XML SAX event parsers work.

XML Parsing
16

The XMLParser started its life as an HTML parser built for displaying mobile HTML.
That usage has since been deprecated but the parser can still parse many HTML pages
and is very "loose" in terms of verification. This is both good and bad as the parser will
work with invalid data without complaining.
The simplest usage of XMLParser looks a bit like this:
XMLParser parser = new XMLParser();

Element elem = parser.parse(reader);

17

The Element contains children and attributes. It represents a tag within the XML
document and even the root document itself. You can iterate over the XML tree to
extract the data from within the XML file.
Weve had a great sample of working with XMLParser in the Tree Section of this
guide.
18

XMLParser has the complimentary XMLWriter class which can generate XML from
the Element hierarchy. This allows a developers to mutate (modify) the elements and
save them to a writer stream.

XPath Processing
19

20

The Result class provides a subset of XPath , but it is not limited to just XML
documents, it can also work with JSON documents, and even with raw Map objects.
16

https://www.codenameone.com/javadoc/com/codename1/xml/XMLParser.html
17
https://www.codenameone.com/javadoc/com/codename1/xml/Element.html
18
https://www.codenameone.com/javadoc/com/codename1/xml/XMLWriter.html
19
https://www.codenameone.com/javadoc/com/codename1/processing/Result.html
20
http://www.w3schools.com/xsl/xpath_intro.asp

471

File System, Storage, Network & Parsing

Lets start by demonstrating how to process a response from the Google Reverse
21
Geocoder API . Lets start with this XML snippet:
<?xml version="1.0" encoding="UTF-8"?>
<GeocodeResponse>
<status>OK</status>

<result> <!-- (irrelevant content removed) -->

<address_component>
<long_name>London</long_name>
<short_name>London</short_name>
<type>locality</type>
<type>political</type>
</address_component>

<!-- (irrelevant content removed) -->

<address_component>
<long_name>Ontario</long_name>
<short_name>ON</short_name>
<type>administrative_area_level_1</type>
<type>political</type>
</address_component>
<address_component>
<long_name>Canada</long_name>
<short_name>CA</short_name>
<type>country</type>
<type>political</type>
</address_component>
</result>
</GeocodeResponse>

We want to extract some of the data above into simpler string results. We can do this
using:
Result result = Result.fromContent(input, Result.XML);
String country = result.getAsString("/result/
address_component[type='country']/long_name");
String region = result.getAsString("/result/
address_component[type='administrative_area_level_1']/long_name");
String city = result.getAsString("/result/
address_component[type='locality']/long_name");

21

https://developers.google.com/maps/documentation/geocoding/

472

File System, Storage, Network & Parsing

If you are at all familiar with processing responses from webservices, you will notice
that what would normally require several lines of code of selecting and testing nodes
in regular java can now be done in a single line using the new path expressions.
In the code above, input can be any of:
InputStream
directly
ConnectionRequest.readResponse(java.io.InputStream) .

from

XML or JSON document in the form of a {@code String}</li>

XML DOM Element

22

returned from XMLParser

JSON DOM Map returned from JSONParser

23

24

To use the expression processor when calling a webservice, you could use something
like the following to parse JSON (notice this is interchangeable between JSON and
XML):
Form hi = new Form("Location", new BoxLayout(BoxLayout.Y_AXIS));

hi.add("Pinpointing Location");
Display.getInstance().callSerially(() -> {
Location l =
Display.getInstance().getLocationManager().getCurrentLocationSync();
ConnectionRequest request = new ConnectionRequest("http://

maps.googleapis.com/maps/api/geocode/json", false) {
private String country;
private String region;
private String city;
private String json;
@Override
{

protected void readResponse(InputStream input) throws IOException

Result result = Result.fromContent(input, Result.JSON);

country = result.getAsString("/results/
address_components[types='country']/long_name");
region = result.getAsString("/results/
address_components[types='administrative_area_level_1']/long_name");
city = result.getAsString("/results/
address_components[types='locality']/long_name");
json = result.toString();
22
23
24

https://www.codenameone.com/javadoc/com/codename1/xml/Element.html
https://www.codenameone.com/javadoc/com/codename1/xml/XMLParser.html
https://www.codenameone.com/javadoc/com/codename1/io/JSONParser.html

473

File System, Storage, Network & Parsing

}
@Override

protected void postResponse() {

hi.removeAll();
hi.add(country);
hi.add(region);
hi.add(city);

hi.add(new SpanLabel(json));
}

hi.revalidate();

};
request.setContentType("application/json");
request.addRequestHeader("Accept", "application/json");
request.addArgument("sensor", "true");
request.addArgument("latlng", l.getLatitude() + "," +
l.getLongitude());
NetworkManager.getInstance().addToQueue(request);

});
hi.show();
[source,java]

The returned JSON looks something like this (notice its snipped because the data is
too long):
{

"status": "OK",
"results": [
{
"place_id": "ChIJJ5T9-iFawokRTPGaOginEO4",
"formatted_address": "280 Broadway, New York, NY 10007, USA",
"address_components": [
{
"short_name": "280",
"types": ["street_number"],
"long_name": "280"
},
{
"short_name": "Broadway",
"types": ["route"],
"long_name": "Broadway"
},
{
"short_name": "Lower Manhattan",

474

File System, Storage, Network & Parsing

"types": [

"neighborhood",
"political"

],

"long_name": "Lower Manhattan"

},
{

"short_name": "Manhattan",
"types": [
"sublocality_level_1",
"sublocality",
"political"
],
"long_name": "Manhattan"

},
{

"short_name": "New York",

"types": [
"locality",
"political"
],
"long_name": "New York"

},
{

"short_name": "New York County",

"types": [
"administrative_area_level_2",
"political"
],
"long_name": "New York County"

},
{

"short_name": "NY",
"types": [
"administrative_area_level_1",
"political"
],
"long_name": "New York"

},
{

"short_name": "US",
"types": [
"country",
"political"
],
"long_name": "United States"

475

File System, Storage, Network & Parsing

},
{

"short_name": "10007",
"types": ["postal_code"],
"long_name": "10007"

},
{

"short_name": "1868",
"types": ["postal_code_suffix"],
"long_name": "1868"

],
"types": ["street_address"],
"geometry": {
"viewport": {
"northeast": {
"lng": -74.0044642197085,
"lat": 40.7156470802915

},
"southwest": {
"lng": -74.0071621802915,
"lat": 40.7129491197085
}

},
"location_type": "ROOFTOP",
"location": {
"lng": -74.00581319999999,
"lat": 40.7142981
}

/* SNIPED the rest */

476

File System, Storage, Network & Parsing

Figure 11.8. Running the geocode sample above in the simulator

The XML processor currently handles global selections by using a double slash
anywhere within the expression, for example:
// get all address_component names anywhere in the document with a type
"political"

String array[] = result.getAsStringArray("//

address_component[type='political']/long_name");
// get all types anywhere under the second result (dimension is 0-based)
String array[] = result.getAsStringArray("/result[1]//type");

477

File System, Storage, Network & Parsing

Notice that Googles JSON webservice uses plural form for each
of the node names in that API (ie. results, address_components,
and types) where they dont in the XML services (ie result,
address_component etc.)

Second Example
It also possible to do some more complex expressions. Well use the following XML
fragment for the next batch of examples:
<rankings type="aus" gender="male" date="2011-12-31">

<player id="1036" coretennisid="6752" rank="1" delta="0" singlespoints="485000" double

<firstname>Bernard</firstname>
<lastname>Tomic</lastname>
<town>SOUTHPORT</town>
<state>QLD</state>
<dob>1992-10-21</dob>
</player>

<player id="2585" coretennisid="1500" rank="2" delta="0" singlespoints="313500" double

<firstname>Mathew</firstname>
<lastname>Ebden</lastname>
<town>CHURCHLANDS</town>
<state>WA</state>
<dob>1987-11-26</dob>
</player>

<player id="6457" coretennisid="287" rank="3" delta="0" singlespoints="132500" doubles

<firstname>Lleyton</firstname>
<lastname>Hewitt</lastname>
<town>EXETER</town>
<state>SA</state>
<dob>1981-02-24</dob>
</player>
<!-- ... etc ... -->

</rankings>

Above, if you want to select the IDs of all players that are ranked in the top 2, you can
use an expression like:
int top2[] = result.getAsIntegerArray("//player[@rank < 3]/@id");

478

File System, Storage, Network & Parsing

Notice above that the expression is using an attribute for selecting
both rank and id. In JSON documents, if you attempt to select an
attribute, it will look for a child node under the attribute name you
ask for)
If a document is ordered, you might want to select nodes by their position, for example:
String first2[] = result.getAsStringArray("//player[position() < 3]/
firstname");
String secondLast = result.getAsString("//player[last() - 1]/firstName");

It is also possible to select parent nodes, by using the .. expression. For example:
int id = result.getAsInteger("//lastname[text()='Hewitt']/../@id");

Above, we globally find a lastname element with a value of Hewitt, then grab the parent
node of lastname which happens to be the player node, then grab the id attribute from
the player node. Alternatively, you could get the same result from the following simpler
statement:
int id = result.getAsInteger("//player[lastname='Hewitt']/@id");

It is also possible to nest expressions, for example:

String id=result.getAsInteger("//player[//address[country/isocode='CA']]/
@id");

In the above example, if the player node had an address object, wed be selecting all
players from Canada. This is a simple example of a nested expression, but they can
get much more complex, which will be required as the documents themselves get more
complex.
Moving on, to select a node based on the existence of an attribute:
int id[] = result.getAsIntegerArray("//player[@rank]/@id");

Above, we selected the IDs of all ranked players. Conversely, we can select the nonranked players like this:
479

File System, Storage, Network & Parsing

int id[] = result.getAsIntegerArray("//player[@rank=null]/@id");

Logical not (!) operators currently are not implemented)

You can also select by the existence of a child node

int id[] = result.getAsIntegerArray("//player[middlename]/@id");

Above, we selected all players that have a middle name.<br/> Keep in mind that the
Codename One path expression language is not a full implementation of XPath 1.0,
but does already handle many of the most useful features of the specification.

Properties Files
25

Properties files are standard key/value pairs encoded into a text file. This file format
is very familiar to Java developers and the Codename One specific version tries to be
as close as possible to the original Java implementation.
Notice that properties file both in Java proper and in Codename One dont support nonascii characters. In order to encode unicode values into the properties file format you
should use the native2ascii tool that ships with the JDK.

25

https://www.codenameone.com/javadoc/com/codename1/io/Properties.html

480

File System, Storage, Network & Parsing

11.6.Debugging Network Connections

Figure 11.9. Debugging Network Connections

Codename One includes a Network Monitor tool which you can access via the simulator
menu option. This tool reflects all the requests made through the connection requests
and displays them in the left pane. This allows you to track issues in your code/web
service and see everything the is "going through the wire".
This is a remarkably useful tool for optimizing and for figuring out what exactly is
happening with your server connection logic.

11.6.1.Simpler Downloads
A very common task is file download to storage or filesystem.
The Util

26

class has simple utility methods:

downloadUrlToFileSystemInBackground ,
downloadUrlToStorageInBackground,
downloadUrlToStorage .
26

downloadUrlToFile

https://www.codenameone.com/javadoc/com/codename1/io/Util.html

481

&

File System, Storage, Network & Parsing

These all delegate to a feature in ConnectionRequest

27

ConnectionRequest.setDestinationStorage(fileName) / ConnectionRequest.setDe
Both of which simplify the whole process of downloading a file.

Downloading Images
Codename One has multiple ways to download an image and the general
28
recommendation is the URLImage . However, the URLImage assumes that you
know the size of the image in advance or that you are willing to resize it. In that regard
it works great for some use cases but not so much for others.
The download methods mentioned above are great alternatives but they are a bit
verbose when working with images and dont provide fine grained control over the
ConnectionRequest e.g. making a POST request to get an image.
Adding global headers is another use case but you can use
29
addDefaultHeader to add those.
To make this process simpler there is a set of helper methods in ConnectionRequest
30
that downloads images directly .
These methods complement the Util methods but go a bit further and feature very
terse syntax e.g. you can just download a ConnectionRequest to Storage using
code like this:
request.downloadImageToStorage(url, (img) ->
theImageIsHereDoSomethingWithIt(img));

This effectively maps the ConnectionRequest directly to a SuccessCallback

further processing.
27
28
29

31

for

https://www.codenameone.com/javadoc/com/codename1/io/ConnectionRequest.html
https://www.codenameone.com/javadoc/com/codename1/ui/URLImage.html

https://www.codenameone.com/javadoc/com/codename1/io/NetworkManager.html#addDefaultHeaderjava.lang.String-java.lang.String30
https://www.codenameone.com/javadoc/com/codename1/io/
ConnectionRequest.html#downloadImageToStorage-java.lang.Stringcom.codename1.util.SuccessCallback31
https://www.codenameone.com/javadoc/com/codename1/util/SuccessCallback.html

482

File System, Storage, Network & Parsing

11.7.Webservice Wizard
The Webservice Wizard can be invoked directly from the plugin. It generates stubs for
the client side that allow performing simple method invocations on the server. It also
generates a servlet that can be installed on any servlet container to intercept client
side calls.
There are limits to the types of values that can be passed via the webservice wizard
protocol but it is highly efficient since it is a binary protocol and very extensible
thru object externalization. All methods are provided both as asynchronous and
synchronous calls for the convenience of the developer.

Figure 11.10. The first step in creating a client/server connection

using the webservice wizard is to create a web application

483

File System, Storage, Network & Parsing

Figure 11.11. Any name will do

Normally you should have a server setup locally. I use Tomcat since its really trivial
and I dont really need much but there are many great Java webservers out there and
this should work with all of them!

Figure 11.12. Setup your webserver in the IDE

484

File System, Storage, Network & Parsing

Figure 11.13. Configure the application server to the newly created

app, notice the application context value which we will use later

485

File System, Storage, Network & Parsing

Figure 11.14. In the main Codename One project right click and
select the WebService Wizard option

486

File System, Storage, Network & Parsing

Figure 11.15. Set the package and class name for the webservice
abstraction (notice this isnt your main class name) and then add
the methods you want in the webservice

487

File System, Storage, Network & Parsing

Figure 11.16. Add the methods and their arguments/return types.

Once you finished adding all of those press the "Generate" button
The types of arguments are pretty limited however you can pass an
arbitrary Externalizable object which can be "anything"

488

File System, Storage, Network & Parsing

Figure 11.17. Pick the directory in the server project to which the
source files will be generated by default this is the src/java directory
under the project we created in the first step

Figure 11.18. If you saved to the right location the server project
directory should look like this

489

File System, Storage, Network & Parsing

We can now open the GameOfThronesServiceServer.java file in the server and
it looks like this:
public class GameOfThronesServiceServer {

public static String[] getBookNames() {

// your code goes here...

return null;

public static String[] getBookPovCharacters(String bookName) {

// your code goes here...

return null;

All we need to do is fill in the code, for this example well only implement the first method
for simplicity:
public class GameOfThronesServiceServer {

public static String[] getBookNames() {

return new String[] {

"A Game of Thrones", "A Clash Of Kings", "A Storm Of

Swords", "A Feast For Crows",
"A Dance With Dragons", "The Winds of Winter", "A Dream of
Spring"
};
}
public static String[] getBookPovCharacters(String bookName) {
// your code goes here...

return null;

Now lets open the client side code, in the GameOfThronesService.java file we
see this
public class GameOfThronesService {

private static final String DESTINATION_URL = "http://localhost:8080/

cn1proxy";
//...

490

File System, Storage, Network & Parsing

}

The destination URL needs to point at the actual server which you will recall from the
new project creation should include "HelloWebServiceWizard". So we can fix the URL
to:
private static final String DESTINATION_URL = "http://localhost:8080/
HelloWebServiceWizard/cn1proxy";

You would naturally need to update the host name of the server for running on a device
otherwise the device would need to reside within your internal network and point to
your IP address.
It is now time to write the actual client code that calls this. Every method we defined
above is now defined as a static method within the GameOfThronesService class
with two permutations. One is a synchronous permutation that behaves exactly as
expected. It blocks the calling thread while calling the server and might throw an
IOException if something failed.
This type of method (synchronous method) is very easy to work with since its
completely legal to call it from the event dispatch thread and its very easy to map it
to application logic flow.
The second type of method uses the async JavaScript style callbacks and accepts the
callback interface. It returns immediately and doesnt throw any exception. It will call
onSuccess/onError based on the server result.
You can pick either one of these approaches based on your personal preferences. Here
we demonstrate both uses with the server API:
Form hi = new Form("WebService Wizard", new BoxLayout(BoxLayout.Y_AXIS));
Button getNamesSync = new Button("Get Names - Sync");

Button getNamesASync = new Button("Get Names - ASync");

hi.add(getNamesSync).add(getNamesASync);
getNamesSync.addActionListener((e) -> {
try {

String[] books = GameOfThronesService.getBookNames();

hi.add("--- SYNC");
for(String b : books) {
}

hi.add(b);

491

File System, Storage, Network & Parsing

hi.revalidate();

} catch(IOException err) {

});

Log.e(err);

getNamesASync.addActionListener((e) -> {

GameOfThronesService.getBookNamesAsync(new Callback<String[]>() {
@Override

public void onSucess(String[] value) {

hi.add("--- ASYNC");

for(String b : value) {
hi.add(b);

}
hi.revalidate();

@Override

public void onError(Object sender, Throwable err, int errorCode,

String errorMessage) {
Log.e(err);
}
});
});

492

File System, Storage, Network & Parsing

Figure 11.19. The final result of the WebService Wizard code

11.8.Cached Data Service

32

The CachedDataService allows caching data and only updating it if the data changed
on the server. Normally the download APIs wont check for update if there is a local
cache of the data (e.g. URLImage always uses the local copy). This isnt a bad thing,
its pretty efficient.

32

https://www.codenameone.com/javadoc/com/codename1/io/services/CachedDataService.html

493

File System, Storage, Network & Parsing

However, it might be important to update the image if it changed but we still want
caching.
The CachedDataService will fetch data if it isnt cached locally and cache it. When
you "refresh" it will send a special HTTP request that will only send back the data if it
has been updated since the last refresh:
CachedDataService.register();
CachedData d =
(CachedData)Storage.getInstance().readObject("LocallyCachedData");
if(d == null) {

d = new CachedData();

d.setUrl("http://....");

// check if there is a new version of this on the server

CachedDataService.updateData(d, new ActionListener() {
public void actionPerformed(ActionEvent ev) {

// invoked when/if the data arrives, we now have a fresh cache

});

Storage.getInstance().writeObject("LocallyCachedData", d);

11.9.Externalizable Objects
33

Codename One provides the Externalizable interface, which is similar to the Java
SE Externalizable interface. This interface allows an object to declare itself as
Externalizable for serialization (so an object can be stored in a file/storage or sent
over the network). However, due to the lack of reflection and use of obfuscation these
34
objects must be registered with the Util class.
Codename One doesnt support the Java SE Serialization API due to the size issues
and complexities related to obfuscation.
The major objects that are supported by default in the Codename One
Externalizable are: String , Collection , Map , ArrayList , HashMap ,
Vector , Hashtable , Integer , Double , Float , Byte , Short , Long ,
Character , Boolean , Object[] , byte[] , int[] , float[] , long[] ,
double[] .
33
34

https://www.codenameone.com/javadoc/com/codename1/io/Externalizable.html
https://www.codenameone.com/javadoc/com/codename1/io/Util.html

494

File System, Storage, Network & Parsing

Externalizing an object such as h below should work just fine:
Map<String, Object> h = new HashMap<>();
h.put("Hi","World");

h.put("data", new byte[] {(byte)1});

Storage.getInstance().writeObject("Test", h);

However, notice that some things arent polymorphic e.g. if we will externalize a
String[] we will get back an Object[] since String arrays arent detected by
the implementation.
The externalization process caches objects so the app will seem to
work and only fail on restart!
Implementing the Externalizable interface is only important when we want
to store a proprietary object. In this case we must register the object with the
com.codename1.io.Util class so the externalization algorithm will be able to
recognize it by name by invoking:
Util.register("MyClass", MyClass.class);

You should do this early on in the app e.g. in the init(Object)

but you shouldnt do it in a static initializer within the object as that
might never be invoked!
An Externalizable object must have a default public constructor and must
implement the following 4 methods:
public int getVersion();

public void externalize(DataOutputStream out) throws IOException;

public void internalize(int version, DataInputStream in) throws
IOException;

public String getObjectId();

The getVersion() method returns the current version of the object allowing the
stored data to change its structure in the future (the version is then passed when
internalizing the object). The object id is a String uniquely representing the object; it
usually corresponds to the class name (in the example above the Unique Name should
be MyClass ).
495

File System, Storage, Network & Parsing

Its a common mistake to use getClass().getName() to
implement getObjectId() and it would seem to work in the

simulator. This isnt the case though!

Since devices obfuscate the class names this becomes a problem
as data is stored in a random name that changes with every release.
Developers need to write the data of the object in the externalize method using the
methods in the data output stream and read the data of the object in the internalize
method e.g.:
public void externalize(DataOutputStream out) throws IOException {
out.writeUTF(name);
if(value != null) {

out.writeBoolean(true);
out.writeUTF(value);

} else {
}

out.writeBoolean(false);

if(domain != null) {

out.writeBoolean(true);
out.writeUTF(domain);

} else {

out.writeBoolean(false);

}
out.writeLong(expires);

public void internalize(int version, DataInputStream in) throws

IOException {
name = in.readUTF();

if(in.readBoolean()) {
}

value = in.readUTF();

if(in.readBoolean()) {

domain = in.readUTF();

}
expires = in.readLong();

Since strings might be null sometimes we also included convenience methods to

implement such externalization. This effectively writes a boolean before writing the UTF
to indicate whether the string is null:

496

File System, Storage, Network & Parsing

public void externalize(DataOutputStream out) throws IOException {

Util.writeUTF(name, out);
Util.writeUTF(value, out);
Util.writeUTF(domain, out);
out.writeLong(expires);

public void internalize(int version, DataInputStream in) throws

IOException {
name = Util.readUTF(in);
value = Util.readUTF(in);
domain = Util.readUTF(in);
expires = in.readLong();

Assuming we added a new date field to the object we can do the following. Notice that
a Date is really a long value in Java that can be null. For completeness the full
class is presented below:
public class MyClass implements Externalizable {
private static final int VERSION = 2;
private String name;

private String value;

private String domain;

private Date date;

private long expires;

public MyClass() {}
public int getVersion() {
}

return VERSION;

public String getObjectId() {

}

return "MyClass";

public void externalize(DataOutputStream out) throws IOException {

Util.writeUTF(name, out);
Util.writeUTF(value, out);
Util.writeUTF(domain, out);
if(date != null) {

out.writeBoolean(true);
out.writeLong(date.getTime());

497

File System, Storage, Network & Parsing

} else {

out.writeBoolean(false);

}
out.writeLong(expires);

public void internalize(int version, DataInputStream in) throws

IOException {
name = Util.readUTF(in);
value = Util.readUTF(in);
domain = Util.readUTF(in);
if(version > 1) {

boolean hasDate = in.readBoolean();

if(hasDate) {
}

date = new Date(in.readLong());

}
expires = in.readLong();

Notice that we only need to check for compatibility during the reading process as the
writing process always writes the latest version of the data.

11.10.UI Bindings & Utilities

Codename One provides several tools to simplify the path between networking/IO &
GUI. A common task of showing a wait dialog or progress indication while fetching
35
network data can be simplified by using the InfiniteProgress class e.g.:
InfiniteProgress ip = new InfiniteProgress();
Dialog dlg = ip.showInifiniteBlocking();
request.setDisposeOnCompletion(dlg);

The process of showing a progress bar for a long IO operation such as downloading
36
is automatically mapped to the IO stream in Codename One using the SliderBridge
class.
You can simulate network delays and disconnected network in the
Simulator menu
35
36

https://www.codenameone.com/javadoc/com/codename1/components/InfiniteProgress.html
https://www.codenameone.com/javadoc/com/codename1/components/SliderBridge.html

498

File System, Storage, Network & Parsing

The SliderBridge class can bind a ConnectionRequest to a Slider and
effectively indicate the progress of the download. E.g.:
Form hi = new Form("Download Progress", new BorderLayout());
Slider progress = new Slider();

Button download = new Button("Download");

download.addActionListener((e) -> {

ConnectionRequest cr = new ConnectionRequest("https://

www.codenameone.com/img/blog/new_icon.png", false);
SliderBridge.bindProgress(cr, progress);
NetworkManager.getInstance().addToQueueAndWait(cr);
if(cr.getResponseCode() == 200) {

hi.add(BorderLayout.CENTER, new

ScaleImageLabel(EncodedImage.create(cr.getResponseData())));
hi.revalidate();
}

});
hi.add(BorderLayout.SOUTH, progress).add(BorderLayout.NORTH, download);
hi.show();

499

File System, Storage, Network & Parsing

Figure 11.20. SliderBridge progress for downloading the image in

the slow network mode

11.11.Logging & Crash Protection

37

Codename One includes a Log

API that allows developers to just invoke
Log.p(String) or Log.e(Throwable) to log information to storage.
As part of the premium cloud features it is possible to invoke Log.sendLog() in order to
email a log directly to the developer account. Codename One can do that seamlessly
37

https://www.codenameone.com/javadoc/com/codename1/io/Log.html

500

File System, Storage, Network & Parsing

based on changes printed into the log or based on exceptions that are uncaught or
logged e.g.:
Log.setReportingLevel(Log.REPORTING_DEBUG);
DefaultCrashReporter.init(true, 2);

This code will send a log every 2 minutes to your email if anything was changed. You
can place it within the init(Object) method of your application.
For a production application you can use Log.REPORTING_PRODUCTION which will
only email the log on exception.

11.12.Sockets
At this moment Codename One only supports TCP sockets. Server socket (listen/
accept) is only available on Android and the simulator but not on iOS.
You can check if Sockets are supported using the Socket.isSupported() . You
can test for server socket support using Socket.isServerSocketSupported() .
To use sockets you can use the Socket.connect(String host, int port,
SocketConnection 38 eventCallback) method.
To listen on sockets you can use the Socket.listen(int port, Class
scClass) method which will instantiate a SocketConnection instance (scClass
is expected to be a subclass of SocketConnection ) for every incoming connection.
This simple example allows you to create a server and a client assuming the device
supports both:
public class MyApplication {
private Form current;

public void init(Object context) {

try {

Resources theme = Resources.openLayered("/theme");

UIManager.getInstance().setThemeProps(theme.getTheme(theme.getThemeResourceNames()
[0]));
} catch(IOException e){

e.printStackTrace();

38

https://www.codenameone.com/javadoc/com/codename1/io/SocketConnection.html

501

File System, Storage, Network & Parsing

public void start() {

if(current != null){
current.show();

return;

final Form soc = new Form("Socket Test");

Button btn = new Button("Create Server");
Button connect = new Button("Connect");

final TextField host = new TextField("127.0.0.1");

btn.addActionListener((evt) -> {

soc.addComponent(new Label("Listening: " + Socket.getIP()));

soc.revalidate();

Socket.listen(5557, SocketListenerCallback.class);

});
connect.addActionListener((evt) -> {

Socket.connect(host.getText(), 5557, new SocketConnection() {

@Override

public void connectionError(int errorCode, String message)

System.out.println("Error");

@Override

public void connectionEstablished(InputStream is,

OutputStream os) {

try {

int counter = 1;

while(isConnected()) {

os.write(("Hi: " + counter).getBytes());

counter++;
Thread.sleep(2000);

} catch(Exception err) {

});

});

err.printStackTrace();

soc.setLayout(new BoxLayout(BoxLayout.Y_AXIS));
soc.addComponent(btn);
soc.addComponent(connect);
soc.addComponent(host);
soc.show();

502

File System, Storage, Network & Parsing

}
public static class SocketListenerCallback extends SocketConnection {
private Label connectionLabel;
@Override

public void connectionError(int errorCode, String message) {

}

System.out.println("Error");

private void updateLabel(final String t) {

Display.getInstance().callSerially(new Runnable() {
public void run() {

if(connectionLabel == null) {

connectionLabel = new Label(t);

Display.getInstance().getCurrent().addComponent(connectionLabel);
} else {

connectionLabel.setText(t);

});

}
Display.getInstance().getCurrent().revalidate();

@Override
{

public void connectionEstablished(InputStream is, OutputStream os)

try {

byte[] buffer = new byte[8192];

while(isConnected()) {

int pending = is.available();

if(pending > 0) {

int size = is.read(buffer, 0, 8192);

if(size == -1) {
return;

if(size > 0) {
}

updateLabel(new String(buffer, 0, size));

} else {

Thread.sleep(50);

} catch(Exception err) {

err.printStackTrace();

503

File System, Storage, Network & Parsing

public void stop() {

}

current = Display.getInstance().getCurrent();

public void destroy() {

}

504

Chapter12.Miscellaneous Features
This chapter covers various features of Codename One that dont quite fit in any of the
other chapters :icons: font

12.1.Phone Functions
1

Most of the low level phone functionality is accessible in the Display class. Think of it
as a global central class covering your access to the "system".

12.1.1.SMS
Codename One supports sending SMS messages but not receiving them as this
functionality isnt portable. You can send an SMS using:
Display.getInstance().setSMS("+999999999", "My SMS Message");

Android/Blackberry support sending SMSs in the background without showing the user
anything. iOS & Windows Phone just dont have that ability, the best they can offer is
to launch the native SMS app with your message already in that app. Android supports
that capability as well (launching the OS native SMS app).
The default sendSMS API ignores that difference and simply works interactively on
iOS/Windows Phone while sending in the background for the other platforms.
The getSMSSupport API returns one of the following options:
SMS_NOT_SUPPORTED - for desktop, tablet etc.
SMS_SEAMLESS - sendSMS will not show a UI and will just send in the
background
SMS_INTERACTIVE - sendSMS will show an SMS sending UI
SMS_BOTH - sendSMS can support both seamless and interactive mode, this
currently only works on Android
The sendSMS can accept an interactive argument: sendSMS(String
phoneNumber, String message, boolean interactive)
1

https://www.codenameone.com/javadoc/com/codename1/ui/Display.html

505

Miscellaneous Features
The last argument will be ignored unless SMS_BOTH is returned from
getSMSSupport at which point you would be able to choose one way or the other.

The default behavior (when not using that flag) is the background sending which is the
current behavior on Android.
A typical use of this API would be something like this:
switch(Display.getInstance().getSMSSupport()) {
case Display.SMS_NOT_SUPPORTED:
return;

case Display.SMS_SEAMLESS:

showUIDialogToEditMessageData();
Display.getInstance().sendSMS(phone, data);
return;

default:

Display.getInstance().sendSMS(phone, data);
return;

12.1.2.Dialing
Dialog the phone is pretty trivial, this should open the dialer UI without physically dialing
the phone as that is discouraged by device vendors.
You can dial the phone by using:
Display.getInstance().dial("+999999999");

12.1.3.E-Mail
You can send an email via the platforms native email client with code such as this:
Message m = new Message("Body of message");

Display.getInstance().sendMessage(new String[]

{"[email protected]"}, "Subject of message", m);

You
can
add
one
attachment
setAttachmentMimeType .

by

using

setAttachment

and

You need to use files from FileSystemStorage and NOT

Storage files!

506

Miscellaneous Features
You can add more than one attachment by putting them directly into the attachment
map e.g.:
Message m = new Message("Body of message");

m.getAttachments().put(textAttachmentUri, "text/plain");
m.getAttachments().put(imageAttachmentUri, "image/png");
Display.getInstance().sendMessage(new String[]

{"[email protected]"}, "Subject of message", m);

Some features such as attachments etc. dont work correctly in the

simulator but should work on iOS/Android
2

The email messaging API has an additional ability within the Message class. The
sendMessageViaCloud method allows you to use the Codename One cloud to send
an email without end user interaction. This feature is available to pro users only since
it makes use of the Codename One cloud:
Message m = new Message("<html><body>Check out <a href=\"https://
www.codenameone.com/\">Codename One</a></body></html>");
m.setMimeType(Message.MIME_HTML);

// notice that we provide a plain text alternative as well in the send

method

boolean success = m.sendMessageViaCloudSync("Codename

One", "[email protected]", "Name Of User", "Message Subject",

"Check out Codename One at https://
www.codenameone.com/");

12.2.Contacts API
The contacts API provides us with the means to query the phones address
book, delete elements from it and create new entries into it. To get the
platform specific list of contacts you can use String[]
contacts
=
ContactsManager.getAllContacts();
Notice that on some platforms this will prompt the user for permissions and the user
might choose not to grant that permission. To detect whether this is the case you can
invoke isContactsPermissionGranted() after invoking getAllContacts() .
This can help you adapt your error message to the user.
2

https://www.codenameone.com/javadoc/com/codename1/messaging/Message.html

507

Miscellaneous Features
3

Once you have a Contact you can use the getContactById method, however the
default method is a bit slow if you want to pull a large batch of contacts. The solution
for this is to only extract the data that you need via
getContactById(String id, boolean includesFullName,

boolean includesPicture, boolean includesNumbers, boolean

includesEmail,

boolean includeAddress)

Here you can specify true only for the attributes that actually matter to you.
Another capability of the contacts API is the ability to extract all of the contacts very
quickly. This isnt supported on all platforms but platforms such as Android can really
get a boost from this API as extracting the contacts one by one is remarkably slow on
Android.
You can check if a platform supports the extraction of all the contacts quickly thru
ContactsManager.isGetAllContactsFast() .
When retrieving all the contacts, notice that you should probably not
retrieve all the data and should set some fields to false to perform
a more efficient query
You can then extract all the contacts using code that looks a bit like this, notice that we
use a thread so the UI wont be blocked!
Form hi = new Form("Contacts", new BoxLayout(BoxLayout.Y_AXIS));
hi.add(new InfiniteProgress());

Display.getInstance().scheduleBackgroundTask(() -> {
Contact[] contacts = ContactsManager.getAllContacts(true, true, false,
true, false, false);
Display.getInstance().callSerially(() -> {
hi.removeAll();
for(Contact c : contacts) {

MultiButton mb = new MultiButton(c.getDisplayName());

mb.setTextLine2(c.getPrimaryPhoneNumber());
hi.add(mb);
mb.putClientProperty("id", c.getId());

});
3

}
hi.getContentPane().animateLayout(150);

https://www.codenameone.com/javadoc/com/codename1/contacts/Contact.html

508

Miscellaneous Features
});

hi.show();

Figure 12.1. List of contacts

Notice that we didnt fetch the image of the contact as the performance of loading these
images might be prohibitive. We can enhance the code above to include images by
using slightly more complex code such as this:
The scheduleBackgroundTask method is similar to new
Thread() in some regards. It places elements in a queue instead
of opening too many threads so it can be good for non-urgent tasks
509

Miscellaneous Features

Form hi = new Form("Contacts", new BoxLayout(BoxLayout.Y_AXIS));

hi.add(new InfiniteProgress());

int size = Display.getInstance().convertToPixels(5, true);

FontImage fi = FontImage.createFixed("" + FontImage.MATERIAL_PERSON,

FontImage.getMaterialDesignFont(), 0xff, size, size);
Display.getInstance().scheduleBackgroundTask(() -> {
Contact[] contacts = ContactsManager.getContacts(true, true, false,
true, false, false);
Display.getInstance().callSerially(() -> {
hi.removeAll();
for(Contact c : contacts) {

MultiButton mb = new MultiButton(c.getDisplayName());

mb.setIcon(fi);
mb.setTextLine2(c.getPrimaryPhoneNumber());
hi.add(mb);

mb.putClientProperty("id", c.getId());
Display.getInstance().scheduleBackgroundTask(() -> {
Contact cc = ContactsManager.getContactById(c.getId(),
false, true, false, false, false);
Display.getInstance().callSerially(() -> {
Image photo = cc.getPhoto();
if(photo != null) {

});

});

});

});

mb.setIcon(photo.fill(size, size));
mb.revalidate();

}
hi.getContentPane().animateLayout(150);

510

Miscellaneous Features

Figure 12.2. Contacts with the default photos on the simulator, on

device these will use actual user photos when available
Notice that the code above uses callSerially &
scheduleBackgroundTask in a liberal nested way. This is
important to avoid an EDT violation
You can use createContact(String firstName, String familyName,
String officePhone, String homePhone, String cellPhone, String
email) to add a new contact and deleteContact(String id) to delete a contact.

511

Miscellaneous Features

12.3.Localization & Internationalization (L10N &

I18N)
Localization (l10n) means adapting to a locale which is more than just translating to
a specific language but also to a specific language within environment e.g. en_US !
= en_UK . Internationalization (i18n) is the process of creating one application that
adapts to all locales and regional requirements.

Codename One supports automatic localization and seamless internationalization of

an application using the Codename One design tool.
Although localization is performed in the design tool most features
apply to hand coded applications as well. The only exception is the
tool that automatically extracts localizable strings from the GUI.

Figure 12.3. Localization tool in the Designer

To translate an application you need to use the localization section of the Codename
One Designer. This section features a handy tool to extract localization called Sync
With UI, its a great tool to get you started assuming you used the old GUI builder.
Some fields on some components (e.g. Commands ) are not added when using "Sync
With UI" button. But you can add them manually on the localization bundle and they will
512

Miscellaneous Features
be automatically localized. You can just use the Property Key used in the localization
bundle in the Command name of the form.
You can add additional languages by pressing the Add Locale button.
This generates bundles in the resource file which are really just key/value pairs
mapping a string in one language to another language. You can install the bundle using
code like this:
UIManager.getInstance().setBundle(res.getL10N("l10n", local));

The device language (as an ISO 639 two letter code) could be retrieved with this:
String local = L10NManager.getInstance().getLanguage();

Once installed a resource bundle takes over the UI and every string set to a label (and
label like components) will be automatically localized based on the bundle. You can
4
also use the localize method of UIManager to perform localization on your own:
UIManager.getInstance().localize( "KeyInBundle", "DefaultValue");

The list of available languages in the resource bundle could be retrieved like this. Notice
that this a list that was set by you and doesnt need to confirm to the ISO language
code standards:
Resources res = fetchResourceFile();
Enumeration locales = res.listL10NLocales( "l10n" );

An exception for localization is the TextField / TextArea components both of

which contain user data, in those cases the text will not be localized to avoid accidental
localization of user input.
You can preview localization in the theme mode within the Codename One designer
by selecting Advanced, picking your locale then clicking the theme again.
You can export and import resource bundles as standard Java
properties files, CSV and XML. The formats are pretty standard for
most localization shops, the XML format Codename One supports
4

https://www.codenameone.com/javadoc/com/codename1/ui/plaf/UIManager.html

513

Miscellaneous Features
is the one used by Androids string bundles which means most
localization specialists should easily localize it
The resource bundle is just a map between keys and values e.g. the code below
displays "This Label is localized" on the Label with the hardcoded resource
bundle. It would work the same with a resource bundle loaded from a resource file:
Form hi = new Form("L10N", new BoxLayout(BoxLayout.Y_AXIS));

HashMap<String, String> resourceBudle = new HashMap<String, String>();

resourceBudle.put("Localize", "This Label is localized");
UIManager.getInstance().setBundle(resourceBudle);
hi.add(new Label("Localize"));
hi.show();

Figure 12.4. Localized label

12.3.1.Localization Manager
The L10NManager
localization tasks.

class includes a multitude of features useful for common

It allows formatting numbers/dates & time based on platform locale. It also provides
a great deal of the information you need such as the language/locale information you
need to pick the proper resource bundle.
Form hi = new Form("L10N", new TableLayout(16, 2));

L10NManager l10n = L10NManager.getInstance();

hi.add("format(double)").add(l10n.format(11.11)).
add("format(int)").add(l10n.format(33)).
add("formatCurrency").add(l10n.formatCurrency(53.267)).

add("formatDateLongStyle").add(l10n.formatDateLongStyle(new Date())).
add("formatDateShortStyle").add(l10n.formatDateShortStyle(new

Date())).

add("formatDateTime").add(l10n.formatDateTime(new Date())).

https://www.codenameone.com/javadoc/com/codename1/l10n/L10NManager.html

514

Miscellaneous Features
add("formatDateTimeMedium").add(l10n.formatDateTimeMedium(new

Date())).

add("formatDateTimeShort").add(l10n.formatDateTimeShort(new Date())).
add("getCurrencySymbol").add(l10n.getCurrencySymbol()).
add("getLanguage").add(l10n.getLanguage()).
add("getLocale").add(l10n.getLocale()).
add("isRTLLocale").add("" + l10n.isRTLLocale()).

add("parseCurrency").add(l10n.formatCurrency(l10n.parseCurrency("33.77$"))).
add("parseDouble").add(l10n.format(l10n.parseDouble("34.35"))).
add("parseInt").add(l10n.format(l10n.parseInt("56"))).
add("parseLong").add("" + l10n.parseLong("4444444"));
hi.show();

515

Miscellaneous Features

Figure 12.5. Localization formatting/parsing and information

12.3.2.RTL/Bidi
RTL stands for right to left, in the world of internationalization it refers to languages that
are written from right to left (Arabic, Hebrew, Syriac, Thaana).
Most western languages are written from left to right (LTR), however some languages
are written from right to left (RTL) speakers of these languages expect the UI to flow
in the opposite direction otherwise it seems weird just like reading this word would be
to most English speakers: "drieW".

516

Miscellaneous Features
The problem posed by RTL languages is known as BiDi (Bi-directional) and not as RTL
since the "true" problem isnt the reversal of the writing/UI but rather the mixing of RTL
and LTR together. E.g. numbers are always written from left to right (just like in English)
so in an RTL language the direction is from right to left and once we reach a number
or English text embedded in the middle of the sentence (such as a name) the direction
switches for a duration and is later restored.
The main issue in the Codename One world is in the layouts, which need to reverse on
the fly. Codename One supports this via an RTL flag on all components that is derived
6
from the global RTL flag in UIManager .
Resource bundles can also include special case constant @rtl, which indicates if a
language is written from right to left. This allows everything to automatically reverse.
When in RTL mode the UI will be the exact mirror so WEST will become EAST ,
RIGHT will become LEFT and this would be true for paddings/margins as well.
If you have a special case where you dont want this behavior you will need to wrap
it with an isRTL check. You can also use setRTL on a per Component basis to
disable RTL behavior for a specific Component .
Most UI APIs have special cases for BiDi instead of applying it
globally e.g. AWT introduced constants such as LEADING instead
of making WEST mean the opposite direction. We think that was a
mistake since the cases where you wouldnt want the behavior of
automatic reversal are quite rare.
Codename Ones support for bidi includes the following components:
Bidi algorithm - allows converting between logical to visual representation for
rendering
Global RTL flag - default flag for the entire application indicating the UI should flow
from right to left
Individual RTL flag - flag indicating that the specific component/container should
be presented as an RTL/LTR component (e.g. for displaying English elements within
a RTL UI).
RTL text field input
6

https://www.codenameone.com/javadoc/com/codename1/ui/plaf/UIManager.html

517

Miscellaneous Features
7

Most of Codename Ones RTL support is under the hood, the LookAndFeel global
RTL flag can be enabled using:
UIManager.getInstance().getLookAndFeel().setRTL(true);
Once RTL is activated all positions in Codename One become reversed and the UI
becomes a mirror of itself. E.g. Adding a Toolbar command to the left will actually
make it appear on the right. Padding on the left becomes padding on the right. The
scroll moves to the left etc.
This applies to the layout managers (except for group layout) and most components.
Bidi is mostly seamless in Codename One but a developer still needs to be aware that
his UI might be mirrored for these cases.

12.4.Location - GPS
8

The Location API allows us to track changes in device location or the current user
position.
The Simulator includes a Location Simulation tool that you can
launch to determine the current position of the simulator and debug
location events
The most basic usage for the API allows us to just fetch a device Location, notice that
this API is blocking and can take a while to return:
Location position =
LocationManager.getLocationManager().getCurrentLocationSync();

In order for location to work on iOS you MUST define the build
hint ios.locationUsageDescription and describe why your
application needs access to location. Otherwise you wont get
location updates!

The getCurrentLocationSync() method is very good for cases where you only
need to fetch a current location once and not repeatedly query location. It activates
the GPS then turns it off to avoid excessive battery usage. However, if an application
needs to track motion or position over time it should use the location listener API to
track location as such:
7
8

https://www.codenameone.com/javadoc/com/codename1/ui/plaf/LookAndFeel.html
https://www.codenameone.com/javadoc/com/codename1/location/Location.html

518

Miscellaneous Features
Notice that there is a method called getCurrentLocation()
which will return the current state immediately and might not be
accurate for some cases.
public MyListener implements LocationListener {

public void locationUpdated(Location location) {

}

// update UI etc.

public void providerStateChanged(int newState) {

}

// handle status changes/errors appropriately

LocationManager.getLocationManager().setLocationListener(new
MyListener());

On Android location maps to low level APIs if you disable the usage
of Google Play Services. By default location should perform well if
you leave the Google Play Services on

12.4.1.Location In The Background - Geofencing

Polling location is generally expensive and requires a special permission on iOS. Its
also implemented rather differently both in iOS and Android. Both platforms place
restrictions on the location API usage in the background.
Because of the nature of background location the API is non-trivial. It starts with the
venerable LocationManager but instead of using the standard API you need to use
setBackgroundLocationListener .
Instead of passing a LocationListener instance you need to pass a Class object
instance. This is important because background location might be invoked when the
app isnt running and an object would need to be allocated.

Notice that you should NOT perform long operations in the background listener
callback. IOS wake-up time is limited to approximately 10 seconds and the app could
get killed if it exceeds that time slice.
Notice that the listener can also send events when the app is in the foreground,
therefore it is recommended to check the app state before deciding how to process this
event. You can use Display.isMinimized() to determine if the app is currently
running or in the background.
519

Miscellaneous Features
When implementing this make sure that:
The class passed to the API is a public class in the global scope. Not an inner class
or anything like that!
The class has a public no-argument constructor
You need to pass it as a class literal e.g. MyClassName.class . Dont use
Class.forName("my.package.MyClassName") !
Class names are problematic since device builds are obfuscated, you should only
use literals which the obfuscator detects and handles correctly.

The following code demonstrates usage of the GeoFence API:

Geofence gf = new Geofence("test", loc, 100, 100000);
LocationManager.getLocationManager()

.addGeoFencing(GeofenceListenerImpl.class, gf);

public class GeofenceListenerImpl implements GeofenceListener {

@Override

public void onExit(String id) {

}

@Override

public void onEntered(String id) {

if(Display.getInstance().isMinimized()) {

Display.getInstance().callSerially(() -> {
Dialog.show("Welcome", "Thanks for arriving", "OK", null);
});

} else {

LocalNotification ln = new LocalNotification();

ln.setAlertTitle("Welcome");

false);

ln.setAlertBody("Thanks for arriving!");

Display.getInstance().scheduleLocalNotification(ln, 10,

12.5.Background Music Playback

Codename One supports playing music in the background (e.g. when the app is
minimized) which is quite useful for developers building a music player style application.
520

Miscellaneous Features
This support isnt totally portable since the Android and iOS approaches for background
music playback differ a great deal. To get this to work on Android you need to use the
API: MediaManager.createBackgroundMedia() .
You should use that API when you want to create a media stream that will work even
when your app is minimized.
For iOS you will need to use a special build hint: ios.background_modes=music .
Which should allow background playback of music on iOS and would work with the
createBackgroundMedia() method.

12.6.Capture - Photos, Video, Audio

The capture API allows us to use the camera to capture photographs or the microphone
to capture audio. It even includes an API for video capture.
The API itself couldnt be simpler:
String filePath = Capture.capturePhoto();

Just captures and returns a path to a photo you can either open it using the Image
class or save it somewhere.
The returned file is a temporary file, you shouldnt store a reference
to it and instead copy it locally or work with the Image object
E.g. you can copy the Image to Storage using:
String filePath = Capture.capturePhoto();
if(filePath != null) {

Util.copy(FileSystemStorage.getInstance().openInputStream(filePath),
Storage.getInstance().createOutputStream(myImageFileName));

When running on the simulator the Capture API opens a file

chooser API instead of physically capturing the data. This makes
debugging device or situation specific issues simpler
We can capture an image from the camera using an API like this:
9

https://www.codenameone.com/javadoc/com/codename1/ui/Image.html

521

Miscellaneous Features

Form hi = new Form("Capture", new BorderLayout());

hi.setToolbar(new Toolbar());

Style s = UIManager.getInstance().getComponentStyle("Title");

FontImage icon = FontImage.createMaterial(FontImage.MATERIAL_CAMERA, s);

ImageViewer iv = new ImageViewer(icon);
hi.getToolbar().addCommandToRightBar("", icon, (ev) -> {
String filePath = Capture.capturePhoto();
if(filePath != null) {
try {

DefaultListModel<Image> m =
(DefaultListModel<Image>)iv.getImageList();
Image img = Image.createImage(filePath);
if(m == null) {

m = new DefaultListModel<>(img);
iv.setImageList(m);
iv.setImage(img);

} else {

m.addItem(img);

}
m.setSelectedIndex(m.getSize() - 1);

} catch(IOException err) {

});

Log.e(err);

hi.add(BorderLayout.CENTER, iv);
hi.show();

522

Miscellaneous Features

Figure 12.6. Captured photos previewed in the ImageViewer

We demonstrate video capture in the MediaManager section.
The sample below captures audio recordings and copies them locally under unique
names. It also demonstrates the storage and organization of captured audio:
Form hi = new Form("Capture", BoxLayout.y());
hi.setToolbar(new Toolbar());

Style s = UIManager.getInstance().getComponentStyle("Title");
FontImage icon = FontImage.createMaterial(FontImage.MATERIAL_MIC, s);
FileSystemStorage fs = FileSystemStorage.getInstance();

523

Miscellaneous Features
String recordingsDir = fs.getAppHomePath() + "recordings/";
fs.mkdir(recordingsDir);
try {

for(String file : fs.listFiles(recordingsDir)) {

MultiButton mb = new

MultiButton(file.substring(file.lastIndexOf("/") + 1));
mb.addActionListener((e) -> {
try {

Media m = MediaManager.createMedia(recordingsDir + file,

false);

m.play();

} catch(IOException err) {
}

Log.e(err);

});
hi.add(mb);

hi.getToolbar().addCommandToRightBar("", icon, (ev) -> {

try {

String file = Capture.captureAudio();

if(file != null) {

SimpleDateFormat sd = new SimpleDateFormat("yyyy-MMM-dd-

kk-mm");

String fileName =sd.format(new Date());

String filePath = recordingsDir + fileName;

Util.copy(fs.openInputStream(file),
fs.openOutputStream(filePath));
MultiButton mb = new MultiButton(fileName);
mb.addActionListener((e) -> {
try {

Media m = MediaManager.createMedia(filePath,

false);

m.play();

} catch(IOException err) {
}

Log.e(err);

});
hi.add(mb);
hi.revalidate();

} catch(IOException err) {

});

Log.e(err);

} catch(IOException err) {

524

Miscellaneous Features
Log.e(err);

}
hi.show();

Figure 12.7. Captured recordings in the demo

12.6.1.Asynchronous API
The Capture API also includes a callback based API that uses the
ActionListener interface to implement capture. E.g. we can adapt the previous
sample to use this API as such:

525

Miscellaneous Features

hi.getToolbar().addCommandToRightBar("", icon, (ev) -> {

Capture.capturePhoto((e) -> {
if(e != null && e.getSource() != null) {
try {

DefaultListModel<Image> m =
(DefaultListModel<Image>)iv.getImageList();
Image img = Image.createImage((String)e.getSource());
if(m == null) {

m = new DefaultListModel<>(img);
iv.setImageList(m);
iv.setImage(img);

} else {

m.addItem(img);

}
m.setSelectedIndex(m.getSize() - 1);

} catch(IOException err) {

});

});

Log.e(err);

12.7.Gallery
The gallery API allows picking an image and/or video from the cameras gallery (camera
roll).
Like the Capture API the image returned is a temporary image
that should be copied locally, this is due to device restrictions that
dont allow direct modifications of the gallery
We can adapt the Capture sample above to use the gallery as such:
Form hi = new Form("Capture", new BorderLayout());
hi.setToolbar(new Toolbar());

Style s = UIManager.getInstance().getComponentStyle("Title");
FontImage icon = FontImage.createMaterial(FontImage.MATERIAL_CAMERA, s);
ImageViewer iv = new ImageViewer(icon);
hi.getToolbar().addCommandToRightBar("", icon, (ev) -> {
Display.getInstance().openGallery((e) -> {
if(e != null && e.getSource() != null) {

526

Miscellaneous Features
try {

DefaultListModel<Image> m =
(DefaultListModel<Image>)iv.getImageList();
Image img = Image.createImage((String)e.getSource());
if(m == null) {

m = new DefaultListModel<>(img);
iv.setImageList(m);
iv.setImage(img);

} else {

m.addItem(img);

}
m.setSelectedIndex(m.getSize() - 1);

} catch(IOException err) {
Log.e(err);

});

}
}
}, Display.GALLERY_IMAGE);

hi.add(BorderLayout.CENTER, iv);

There is no need for a screenshot as it will look identical to the

capture image screenshot above
The
last
value
is
the
type
of
be
one
of:
Display.GALLERY_ALL ,
Display.GALLERY_IMAGE .

content
picked
which
Display.GALLERY_VIDEO

can
or

12.8.Analytics Integration
One of the features in Codename One is builtin support for analytic instrumentation.
10
Currently Codename One has builtin support for Google Analytics , which provides
reasonable enough statistics of application usage.
Analytics is pretty seamless for the old GUI builder since navigation occurs via the
Codename One API and can be logged without developer interaction. However, to
begin the instrumentation one needs to add the line:
AnalyticsService.setAppsMode(true);
AnalyticsService.init(agent, domain);
10

https://www.google.com/analytics/

527

Miscellaneous Features
To get the value for the agent value just create a Google Analytics account and add a
domain, then copy and paste the string that looks something like UA-99999999-8 from
the console to the agent string. Once this is in place you should start receiving statistic
events for the application.
If your application is not a GUI builder application or you would like to send more
detailed data you can use the Analytics.visit() method to indicate that you are
entering a specific page.

12.8.1.Application Level Analytics

In 2013 Google introduced an improved application level analytics API that is
specifically built for mobile apps. However, it requires a slightly different API usage.
You can activate this specific mode by invoking setAppsMode(true) .
When using this mode you can also report errors and crashes to the Google analytics
server using the sendCrashReport(Throwable, String message, boolean
fatal) method.
We generally recommend using this mode and setting up an apps analytics account
as the results are more refined.

12.8.2.Overriding The Analytics Implementation

The Analytics API can also be enhanced to support any other form of analytics solution
of your own choosing by deriving the AnalyticsService class.
This allows you to integrate with any 3rd party via native or otherwise by overriding
methods in the AnalyticsService class then invoking:
AnalyticsService.init(new MyAnalyticsServiceSubclass());

Notice that this removes the need to invoke the other

setAppsMode(boolean) .

init

method or

12.9.Native Facebook Support

Check out the ShareButton section it might be enough for most of
your needs.

528

Miscellaneous Features
Codename One supports Facebooks Oauth2
iOS and Android.

11

login and Facebooks single sign on for

12.9.1.Getting Started - Web Setup

To get started first you will need to create a facebook app on the Facebook developer
portal at https://developers.facebook.com/apps/

Figure 12.8. Create New App

You need to repeat the process for web, Android & iOS (web is used by the simulator):

Figure 12.9. Pick Platform

For the first platform you need to enter the app name:

11

https://www.codenameone.com/javadoc/com/codename1/io/Oauth2.html

529

Miscellaneous Features

Figure 12.10. Pick app name

And provide some basic details:

Figure 12.11. Basic details for the app

For iOS we need the bundle ID which is the exact same thing we used in the Google+
login to identify the iOS app its effectively your package name:

Figure 12.12. iOS specific basic details

You should end up with something that looks like this:
530

Miscellaneous Features

Figure 12.13. Finished Facebook app

The Android process is pretty similar but in this case we need the activity name too.
The activity name should match the main class name followed by the
word Stub (uppercase s). E.g. for the main class SociallChat
we would use SocialChatStub as the activity name

Figure 12.14. Android Activity definition

To build the native Android app we must make sure that we setup the keystore correctly
for our application. If you dont have an Android certificate you can use the visual wizard
(in the Android section in the project preferences the button labeled Generate) or use
the command line:
keytool -genkey -keystore Keystore.ks -alias [alias_name] -keyalg RSA keysize 2048 -validity 15000 -dname "CN=[full name], OU=[ou], O=[comp],

531

Miscellaneous Features
L=[City], S=[State], C=[Country Code]" -storepass [password] -keypass
[password]

You can reuse the certificate in all your apps, some developers like
having a different certificate for every app. This is like having one
master key for all your doors, or a huge keyring filled with keys.
With the certificate we need an SHA1 key to further authenticate us to Facebook and
we do this using the keytool command line on Linux/Mac:
keytool -exportcert -alias (your_keystore_alias) -keystore
(path_to_your_keystore) | openssl sha1 -binary | openssl base64

And on Windows:
keytool -exportcert -alias androiddebugkey -keystore %HOMEPATH%\.android
\debug.keystore | openssl sha1 -binary | openssl base64

You can read more about it on the Facebook guide here

12

https://developers.facebook.com/docs/android/getting-started

532

12

Miscellaneous Features

Figure 12.15. Hash generation process, notice the command lines

are listed as part of the web wizard
Lastly you need to publish the Facebook app by flipping the switch in the apps "Status
& Review" page as such:

Figure 12.16. Without flipping the switch the app wont "appear"

533

Miscellaneous Features

12.9.2.IDE Setup
We now need to set some important build hints in the project so it will work correctly.
To set the build hints just right click the project select project properties and in the
Codename One section pick the second tab. Add this entry into the table:
facebook.appId=...

The app ID will be visible in your Facebook app page in the top left position.

12.9.3.The Code
To bind your mobile app into the Facebook app you can use the following code:
Login fb = FacebookConnect.getInstance();
fb.setClientId("9999999");
fb.setRedirectURI("http://www.youruri.com/");
fb.setClientSecret("-------");
// Sets a LoginCallback listener

fb.setCallback(new LoginCallback() {
public void loginSuccessful() {
}

// we can now start fetching stuff from Facebook!

});

public void loginFailed(String errorMessage) {}

// trigger the login if not already logged in

if(!fb.isUserLoggedIn()){
fb.doLogin();

} else {

// get the token and now you can query the Facebook API
String token = fb.getAccessToken().getToken();

// ...

All of these values are from the web version of the app!
They are only used in the simulator and on "unsupported" platforms
as a fallback. Android and iOS will use the native login
534

Miscellaneous Features

12.9.4.Facebook Publish Permissions

In order to post something to Facebook you need to request a write permission, you can
only do write operations within the callback which is invoked when the user approves
the permission.
You can prompt the user for publish permissions by using this code on a logged in
FacebookConnect

13

FacebookConnect.getInstance()askPublishPermissions(new LoginCallback() {
public void loginSuccessful() {
}

// do something...

public void loginFailed(String errorMessage) {

});

// show error or just ignore

Notice that this wont always prompt the user, but its required to verify
that your token is valid for writing.

12.10.Google Login
We can add login to Googles social account by going to the Google developer console:
https://console.developers.google.com/
Create a new app by pressing the create button:

Figure 12.17. Google developer console

Just enter the name of the app e.g. for this case its SocialChat and press "Create":

13

https://www.codenameone.com/javadoc/com/codename1/social/FacebookConnect.html

535

Miscellaneous Features

Figure 12.18. Application name

In the new project page we should navigate deeper into the auth APIs for Google+:

Figure 12.19. API catalog

In that project you should click the Google+ API in the "Social" section:

536

Miscellaneous Features

Figure 12.20. Google+ section

In the credentials section create a new client id, first we need to create one for a web
application.
This will be used by the simulator so we can debug the application on the desktop. It
will also be used by ports for JavaScript, Desktop and effectively everything other than
iOS & Android:

Figure 12.21. Create web application binding

The consent screen is used to prompt users for permissions, you should normally fill
it up properly for a "real world" application but in this case we left it mostly empty for
simplicities sake:
537

Miscellaneous Features

Figure 12.22. This data will be shown to users when they want to
understand who has access to their account

538

Miscellaneous Features

Figure 12.23. OAuth details, the callback URI should generally point
to your website
We now need to add Android/iOS native app bindings in much the same way as we
did the web app.
To build a native Android app make sure you setup the keystore correctly for
your application. Check out the Facebook authentication section above for a similar
discussion.
Now that you have a certificate you need two values for your app, the first is the package
name which must match the package name of your main class (the one with the start,
stop methods). It should be listed in the Codename One properties section.
539

Miscellaneous Features
Make sure to use a name that is 100% unique to you and using your own domain, dont
use the com.codename1 prefix or anything such as that
You also need the SHA1 value for your certificate, this is explained by Google here:
https://developers.google.com/+/mobile/android/getting-started
Effectively you need to run this command line:
$ keytool -exportcert -alias androiddebugkey -keystore ~/.android/
debug.keystore -list -v

This will prompt for a password then print several lines of data one of which should start
with SHA1 that is the value that you will need for the Android app.

540

Miscellaneous Features

Figure 12.24. Paste the SHA1 value here

The iOS app needs the same package name as the bundle id. It also needs the appstore
id which you can get from itunes connect, it should appear as the prefix for your apps
541

Miscellaneous Features
provisioning profile. If your app is correctly configured e.g. by using the Codename One
certificate wizard, then you should see it in the project properties under the Codename
OneiOS section.

Figure 12.25. iOS App settings

After everything is completed you should see something similar to this:

542

Miscellaneous Features

Figure 12.26. The final result on the web setup

12.10.1.Project Configuration
We now need to set some important build hints in the project so it will work correctly.
To set the build hints just right click the project select project properties and in the
Codename One section pick the second tab. Add these entries into the table:
ios.gplus.clientId=your ios client ID

543

Miscellaneous Features

12.10.2.The Code
The final login code is very similar to the Facebook login code
Login gc = GoogleConnect.getInstance();
gc.setClientId("*****************.apps.googleusercontent.com");
gc.setRedirectURI("https://yourURL.com/");
gc.setClientSecret("-------------------");
// Sets a LoginCallback listener

gc.setCallback(new LoginCallback() {
public void loginSuccessful() {
}

// we can now start fetching stuff from Google+!

});

public void loginFailed(String errorMessage) {}

// trigger the login if not already logged in

if(!gc.isUserLoggedIn()){
gc.doLogin();

} else {

// get the token and now you can query the Google API
String token = gc.getAccessToken().getToken();

544

Miscellaneous Features

// ...

The clientid/secret etc. are only relevant for the simulator and should
be taken from the web app. The native login automatically connects
to the right app.

12.11.Lead Component
Codename One has two basic ways to create new components:
1. Subclass a Component override paint , implement event callbacks etc.
2. Compose multiple components into a new component, usually by subclassing a
Container .
14

Components such as Tabs subclass Container which make a lot of sense for that
component since it is physically a Container .
15

16

17

However, components like MultiButton , SpanButton

& SpanLabel
dont
necessarily seem like the right candidate for compositing but they are all Container
subclasses.
Using a Container provides us a lot of flexibility in terms of layout & functionality for
a specific component. MultiButton is a great example of that. Its a Container
internally that is composed of 5 labels and a Button .
Codename One makes the MultiButton "feel" like a single button thru the use of
setLeadComponent(Component) which turns the button into the "leader" of the
component.
When a Container hierarchy is placed under a leader all events within the hierarchy

are sent to the leader, so if a label within the lead component receives a pointer pressed
event this event will really be sent to the leader.
E.g. in the case of the MultiButton the internal button will receive that event and
send the action performed event, change the state etc.
This creates some potential issues for instance in MultiButton :
14
https://www.codenameone.com/javadoc/com/codename1/ui/Tabs.html
15
https://www.codenameone.com/javadoc/com/codename1/components/MultiButton.html
16
https://www.codenameone.com/javadoc/com/codename1/components/SpanButton.html
17
https://www.codenameone.com/javadoc/com/codename1/components/SpanLabel.html

545

Miscellaneous Features

myMultiButton.addActionListener((e) -> {

if(e.getComponent() == myMultiButton) {
}

// this won't occur since the source component is really a button!

if(e.getActualComponent() == myMultiButton) {

});

// this will happen...

The leader also determines the style state, so all the elements being lead are in the
same state. E.g. if the the button is pressed all elements will display their pressed
states, notice that they will do so with their own styles but they will each pick the pressed
version of that style so a Label UIID within a lead component in the pressed state
would return the Pressed state for a Label not for the Button .
This is very convenient when you need to construct more elaborate UIs and the cool
thing about it is that you can do this entirely in the designer which allows assembling
containers and defining the lead component inside the hierarchy.
E.g. the SpanButton class is very similar to this code:
public class SpanButton extends Container {
private Button actualButton;
private TextArea text;

public SpanButton(String txt) {

setUIID("Button");

setLayout(new BorderLayout());

text = new TextArea(getUIManager().localize(txt, txt));

text.setUIID("Button");
text.setEditable(false);
text.setFocusable(false);

actualButton = new Button();

addComponent(BorderLayout.WEST, actualButton);
addComponent(BorderLayout.CENTER, text);
setLeadComponent(actualButton);

public void setText(String t) {

}

text.setText(getUIManager().localize(t, t));

546

Miscellaneous Features
public void setIcon(Image i) {
}

actualButton.setIcon(i);

public String getText() {

}

return text.getText();

public Image getIcon() {

}

return actualButton.getIcon();

public void addActionListener(ActionListener l) {

}

actualButton.addActionListener(l);

public void removeActionListener(ActionListener l) {

}

actualButton.removeActionListener(l);

12.11.1.Blocking Lead Behavior

The Component class has two methods that allow us to exclude a component from
lead behavior: setBlockLead(boolean) & isBlockLead() .
Effectively when you have a Component within the lead hierarchy that you would like
to treat differently from the rest you can use this method to exclude it from the lead
component behavior while keeping the rest in line
This should have no effect if the component isnt a part of a lead component.
The sample below is based on the Accordion component which uses a lead
component internally.
Form f = new Form("Accordion", new BorderLayout());
Accordion accr = new Accordion();

f.getToolbar().addMaterialCommandToRightBar("", FontImage.MATERIAL_ADD, e
-> addEntry(accr));
addEntry(accr);
f.add(BorderLayout.CENTER, accr);
f.show();

547

Miscellaneous Features
void addEntry(Accordion accr) {

TextArea t = new TextArea("New Entry");

Button delete = new Button();

FontImage.setMaterialIcon(delete, FontImage.MATERIAL_DELETE);
Label title = new Label(t.getText());

t.addActionListener(ee -> title.setText(t.getText()));

delete.addActionListener(ee -> {
accr.removeContent(t);
accr.animateLayout(200);
});
delete.setBlockLead(true);
delete.setUIID("Label");
Container header = BorderLayout.center(title).
add(BorderLayout.EAST, delete);
accr.addContent(header, t);
accr.animateLayout(200);

This allows us to add/edit entries but it also allows the delete button above to actually
work separately. Without a call to setBlockLead(true) the delete button would cat
as the rest of the accordion title.

548

Miscellaneous Features

Figure 12.27. Accordion with delete button entries that work despite
the surrounding lead

12.12.Pull To Refresh
Pull to refresh is the common UI paradigm that Twitter popularized where the user
can pull down the form/container to receive an update. Adding this to Codename One
couldnt be simpler!
Just invoke addPullToRefresh(Runnable) on a scrollable container (or form) and
the runnable method will be invoked when the refresh operation occurs.
Pull
to
refresh
is
InifiniteContainer

implicitly

implements

Form hi = new Form("Pull To Refresh", BoxLayout.y());

hi.getContentPane().addPullToRefresh(() -> {
hi.add("Pulled at " +

L10NManager.getInstance().formatDateTimeShort(new Date()));

});
hi.show();

549

in

the

Miscellaneous Features

Figure 12.28. Pull to refresh demo

12.13.Running 3rd Party Apps Using Displays

execute
18

The Display classs execute method allows us to invoke a URL which is bound
to a particular application.

18

https://www.codenameone.com/javadoc/com/codename1/ui/Display.html

550

Miscellaneous Features
19

This works rather well assuming the application is installed. E.g. this list contains a
set of valid URLs that can be used on iOS to run common applications and use builtin
functionality.
Some URLs might not be supported if an app isnt installed, on Android there isnt
much that can be done but iOS has a canOpenURL method for Objective-C.
On iOS you can use the Display.canExecute() method which returns a
Boolean instead of a boolean which allows us to support 3 result states:
1. Boolean.TRUE - the URL can be executed
2. Boolean.FALSE - the URL isnt supported or the app is missing
3. null - we have no idea whether the URL will work on this platform.
The sample below launches a "godfather" search on IMDB only when this is sure to
work (only on iOS currently). We can actually try to search in the case of null as well
but this sample plays it safe by using the http link which is sure to work:
Boolean can = Display.getInstance().canExecute("imdb:///find?
q=godfather");
if(can != null && can) {

Display.getInstance().execute("imdb:///find?q=godfather");

} else {
}

19

Display.getInstance().execute("http://www.imdb.com");

http://wiki.akosma.com/IPhone_URL_Schemes

551

Chapter13.Performance, Size &

Debugging
13.1.Reducing Resource File Size
Its easy to lose track of size/performance when you are working within the comforts
of a visual tool like the Codename One Designer. When optimizing resource files you
need to keep in mind one thing: its all about image sizes.
Images will take up 95-99% of the resource file size; everything else
pales in comparison.
Like every optimization the first rule is to reduce the size of the biggest images which
will provide your biggest improvements, for this purpose we introduced the ability to see
image sizes in kilobytes. To launch that feature use the menu item Images Image
Sizes (KB) in the designer.

Figure 13.1. Image sizes window that allows us to find the biggest
impact on our RAM/Storage
This produces a list of images sorted by size with their sizes. Often the top entries will
be multi-images, which include HD resolution values that can be pretty large. These
very high-resolution images take up a significant amount of space!
552

Performance, Size & Debugging

Just going to the multi-images, selecting the unnecessary resolutions & deleting these
images can saves significant amounts of space:

Figure 13.2. Removing unused DPIs

You can see the size in KB at the top right side in the designers
image viewer
Applications using the old GUI builder can use the Images Delete Unused Images
menu option (its also under the Images menu). This tool allows detecting and deleting
images that arent used within the theme/GUI.
If you have a very large image that is opaque you might want to consider converting
it to JPEG and replacing the built in PNGs. Notice that JPEGs work on all supported
devices and are typically smaller.

553

Performance, Size & Debugging

Figure 13.3. Convert a MultiImage to use JPEGs instead of PNGs

1

You can use the excellent OptiPng tool to optimize image files right from the
Codename One designer. To use this feature you need to install OptiPng then select
Images Launch OptiPng from the menu. Once you do that the tool will automatically
optimize all your PNGs.
When faced with size issues make sure to check the size of your res file, if your JAR
file is large open it with a tool such as 7-zip and sort elements by size. Start reviewing
which element justifies the size overhead.

13.2.Improving Performance
There are quite a few things you can do as a developer in order to improve the
performance and memory footprint of a Codename One application. This sometimes
depends on specific device behaviors but some of the tips here are true for all devices.
The simulator contains some tools to measure performance overhead of a specific
component and also detect EDT blocking logic. Other than that follow these guidelines
to create more performance code:
Avoid round rect borders - they have a huge overhead on all platforms. Use image
borders instead (counter intuitively they are MUCH faster)
Avoid Gradients - they perform poorly on most OSs. Use a background image
instead
Use larger images when tiling or building image borders, using a 1 pixel (or event
a few pixels) wide or high image and tiling it repeatedly can be very expensive
Shrink resource file sizes - Otherwise data might get collected by the garbage
collector and reloading data might be expensive
1

http://optipng.sourceforge.net/

554

Performance, Size & Debugging

Check that you dont have too many image lock misses - this is discussed in
the graphics section
On some platforms mutable images are slow - mutable images are images you
can draw on (using getGraphics() ). On some platforms they perform quite badly
(e.g. iOS) and should generally be avoided. You can check if mutable images are
fast in a platform using Display.areMutableImagesFast()
* Make components either transparent or opaque * - a translucent component must
paint its parent every time. This can be expensive. An opaque component might
have margins that would require that we paint the parent so there is often overdraw
in such cases (overdraw means the same pixel being painted twice).

13.3.Performance Monitor
The Performance Monitor tool can be accessible via the Simulator Performance
Monitor menu option in the simulator. This launches the following UI that can help you
improve application performance:

Figure 13.4. Main tab of the performance monitor: Logs and timings
The first tab of the performance monitor includes a table of the drawn components.
Each entry includes the number of times it was drawn and the slowest/fastest and
average drawing time.

555

Performance, Size & Debugging

This is useful if a Form is slow. You might be able to pinpoint it to a specific component
using this tool.
The Log on the bottom includes debug related information. E.g. it warns about the
usage of mutable images which might be slow on some platforms. This also displays
warnings when an unlocked image is drawn etc.

Figure 13.5. Rendering tree

The rendering tree view allows us to inspect the hierarchy painting. You can press
the refresh button which will trigger the painting of the current Form . Every graphics
operation is logged and so is the stack to it.
You can then inspect the hierarchy and see what was drawn by the various
components. You can click the "stack" buttons to see the specific stack trace that lead
to that specific drawing operation.
This is a remarkably powerful debugging tool as you can literally see "overdraw" within
this tool. E.g if you see fillRect or similar APIs invoked in the parent and then
again and again in the children this could indicate a problem.
Android devices have a very nice overdraw debugging tool

556

Performance, Size & Debugging

13.4.Network Speed

Figure 13.6. Network speed tool

This feature is actually more useful for general debugging however its sometimes
useful to simulate a slow/disconnected network to see how this affects performance.
For this purpose the Codename One simulator allows you to slow down networking or
even fake a disconnected network to see how your application handles such cases.

13.5.Debugging Codename One Sources

When you debug your app with our source code you can place breakpoints deep within
Codename One and gain unique insight. You can also use the profilers and profile into
Codename One to gain similar performance specific insight.
When you run into a bug or a missing feature you can push that feature/fix back to
2
Codename One using a pull request. Github makes that process trivial and in this new
video and slides below we show you how. The steps to use the code are:
1. Signup for Github
2. Fork http://github.com/codenameone/CodenameOne and http://github.com/
codenameone/codenameone-skins (also star and watch the projects for good
measure).
3. Clone the git URLs from the projects into the IDE using the Team Git Clone
menu option. Notice that you must deselect projects in the IDE for the menu to
appear.
3

4. Download the cn1-binaries project from github here .

5. Unzip the cn1-binaries project and make sure the directory has the name cn1binaries. Verify that cn1-binaries, CodenameOne and codenameone-skins are
within the same parent directory. .In your own project remove the jars both in the
build & run libraries section. Replace the build libraries with the CodenameOne/
2
3

https://www.codenameone.com/
https://github.com/codenameone/cn1-binaries/archive/master.zip

557

Performance, Size & Debugging

CodenameOne project. Replace the runtime libraries with the CodenameOne/
Ports/JavaSEPort project.
This allows you to run the existing Codename One project with the Codename One
source code and debug into Codename One. You can now also commit, push and send
a pull request with the changes.

13.6.Device Testing Framework/Unit Testing

Codename One includes a built in testing framework and test recorder tool as part of
the simulator. This allows developers to build both functional and unit test execution
on top of Codename One. It even enables sending tests for execution on the device
(pro-only feature).
To get started with the testing framework, launch the application and open the test
recorder in the simulator menu.

Figure 13.7. The test recorder tool in the simulator

558

Performance, Size & Debugging

Once you press record a test will be generate for you as you use the application.

Figure 13.8. Test recording in progress, when done just press the
save icon
You can build tests using the Codename One testing package to manipulate the
Codename One UI programmatically and perform various assertions.
Unlike frameworks such as JUnit which assign a method per test, the Codename One
test framework uses a class per test. This allows the framework to avoid reflection and
thus allows it to work properly on the device.

13.7.EDT Error Handler and sendLog

Handling errors or exceptions in a deployed product is pretty difficult, most users would
just throw away your app and some would give it a negative rating without providing
you with the opportunity to actually fix the bug that might have happened.

559

Performance, Size & Debugging

Figure 13.9. Default error dialog

Google improved on this a bit by allowing users to submit stack traces for failures on
Android devices but this requires the users approval for sending personal data which
you might not need if you only want to receive the stack trace and maybe some basic
application state (without violating user privacy).
For quite some time Codename One had a very powerful feature that allows you to
both catch and report such errors, the error reporting feature uses the Codename One
cloud which is exclusive for pro/enterprise users. Normally in Codename One we catch
all exceptions on the EDT (which is where most exceptions occur) and just display an
error to the user as you can see in the picture. Unfortunately this isnt very helpful to us
as developers who really want to see the stack; furthermore we might prefer the user
doesnt see an error message at all!
Codename One allows us to grab all exceptions that occur on the EDT and handle
4
them using the method addEdtErrorHandler in the Display class. Adding this to
the Logs ability to report errors directly to us and we can get a very powerful tool that
will send us an email with information when a crash occurs!
This can be accomplished with a single line of code:
Log.bindCrashProtection(true);

We normally place this in the init(Object) method so all future

on-device errors are emailed to you. Internally this method uses the
Display.getInstance().addEdtErrorHandler() API to bind error listeners
to the EDT. When an exception is thrown there it is swallowed (using
ActionEvent.consume() ). The Log data is then sent using Log.sendLog() .
To truly benefit from this feature we need to use the Log class for all logging and
exception handling instead of APIs such as System.out .
4

https://www.codenameone.com/javadoc/com/codename1/ui/Display.html

560

Performance, Size & Debugging

To log standard printouts you can use the Log.p(String) method and to log
exceptions with their stack trace you can use Log.e(Throwable) .

561

Chapter14.Advanced Topics/Under The

Hood
This chapter covers the more advanced topics explaining how Codename One actually
works. :icons: font

14.1.Sending Arguments To The Build Server

When sending a build to the server we can provide additional parameters to the build,
which are incorporated into the build process on the server to "hint" on multiple different
build time options.
These hints are often referred to as "build hints" or "build arguments", they are
effectively very much like souped up compiler flags that you can use to tune the build
servers behavior. This is useful for fast iteration on new functionality without building
plugin UI for every change. This is also useful for exposing very low level behavior such
as customizing the Android manifest XML or the iOS plist.
You can set these hints by right clicking the project in the IDE and selecting Preferences
then within the Codename One preferences area selecting the Build Hints tab. The
hints use the key=value style of data.

562

Advanced Topics/Under The Hood

Figure 14.1. The build hints UI in NetBeans

563

Advanced Topics/Under The Hood

Figure 14.2. The build hints UI in the Eclipse IDE

In IntelliJ/IDEA this is reachable via the global preferences menu, we
have plans to completely redo the IntelliJ UI

564

Advanced Topics/Under The Hood

Figure 14.3. The build hints UI in IntelliJ/IDEA

You can set the build hints in the codenameone_settings.properties
file directly notice that when you do that all settings need to start
with the codename1.arg. prefix. When editing the properties file directly
we would need to define something like android.debug=true as
codename1.arg.android.debug=true .
Some build hints conflict with GUI settings that are available via
custom UI. E.g. the iOS section in the preferences has an Include
Push checkbox that conflicts with ios.includePush this can
result in build hints that are ignored!
Make sure you use the UI elements when they are available!

565

Advanced Topics/Under The Hood

Figure 14.4. The GUI based settings might conflict with some of the
build hints
Here is the current list of supported arguments, notice that build hints are added all the
time so consult the discussion forum if you dont find what you need here:

Table 14.1. Build hints

Name

Description

android.debug

true/false defaults to true - indicates

whether to include the debug version in
the build

android.release

true/false defaults to true - indicates

whether to include the release version in
the build

android.installLocation

Maps to android:installLocation manifest

entry defaults to auto. Can also be set to
internalOnly or preferExternal.
566

Advanced Topics/Under The Hood

Name

Description

android.gradle

true/false defaults to false prior to 3.3

and true after. Uses Gradle instead of
Ant to build the Android app

android.xapplication

defaults to an empty string. Allows

developers of native Android code to add
text within the application block to define
things such as widgets, services etc.

android.xpermissions

additional permissions for the Android

manifest

android.xintent_filter

Allows adding an intent filter to the main

android activity

android.licenseKey

The license key for the Android app, this

is required if you use in-app-purchase on
Android

android.stack_size

Size in bytes for the Android stack

thread

android.statusbar_hidden

true/false defaults to false. When set

to true hides the status bar on Android
devices.

android.facebook_permissions

Permissions for Facebook used in the

Android build target, applicable only if
Facebook native integration is used.

android.googleAdUnitId

Allows integrating admob/google play

ads, this is effectively identical to
google.adUnitId but only applies to
Android

android.googleAdUnitTestDevice

Device key used to mark a specific

Android device as a test device
for Google Play ads defaults to
C6783E2486F0931D9D09FABC65094FDF

android.includeGPlayServices

Deprecated, please
android.playService.*! Indicates
whether Goolge Play Services should
be included into the build, defaults to
false but that might change based on the

567

Advanced Topics/Under The Hood

Name

Description
functionality of the application and other
build hints. Adding Google Play Services
support allows us to use a more refined
location implementation and invoke
some Google specific functionality from
native code.

android.playService.plus,
android.playService.auth,
android.playService.base,

Allows including only a specific play

services library portion. Notice that this
setting conflicts with the deprecated

android.playService.identity,
android.playService.indexing,
android.playService.appInvite,
android.playService.analytics,
android.playService.cast,
android.playService.gcm,
android.playService.drive,
android.playService.fitness,
android.playService.location,
android.playService.maps,
android.playService.ads,
android.playService.vision,
android.playService.nearby,
android.playService.panorama,
android.playService.games,
android.playService.safetynet,
android.playService.wallet,
android.playService.wearable

android.includeGPlayServices
and only works with the gradle build
(which is on by default but can be
toggled using android.gradle ).

android.headphoneCallback

Boolean true/false defaults to

false. When set to true it assumes
the main class has two methods:

If none of the services are defined to

true then plus, auth, base, analytics,
gcm, location, maps & ads will be
set to true. If one or more of the
android.playService entries are
defined to something then all entries will
default to false.

headphonesConnected &
headphonesDisconnected which it
invokes appropriately as needed
android.gpsPermission

Indicates whether the GPS permission

should be requested, it is auto-detected
by default if you use the location API.

568

Advanced Topics/Under The Hood

Name

Description
However, some code might want to
explicitly define it

android.asyncPaint

Boolean true/false defaults to true.

Toggles the Android pipeline between
the legacy pipeline (false) and new
pipeline (true)

android.stringsXml

Allows injecting additional entries into

the strings.xml file using a value that
includes something like this`<string
name="key1">value1</string><string
name="key2">value2</string>`

android.supportV4

Boolean true/false defaults to false but

that can change based on usage (e.g.
push implicitly activates this). Indicates
whether the android support v4 library
should be included in the build

android.style

Allows injecting additional data into

the styles.xml file right before the
closing resources tag

android.cusom_layout1

Applies to any number of layouts

as long as they are in sequence
(e.g. android.cusom_layout2,
android.cusom_layout3 etc.). Will
write the content of the argument as
a layout xml file and give it the name
cusom_layout1.xml onwards. This
can be used by native code to work with
XML files

android.keyboardOpen

Boolean true/false defaults to true.

Toggles the new async keyboard mode
that leaves the keyboard open while we
move between text components

android.versionCode

Allows overriding the auto generated

version number with a custom internal

569

Advanced Topics/Under The Hood

Name

Description
version number specifically used for the
xml attribute android:versionCode

android.captureRecord

Indicates whether the RECORD_AUDIO

permission should be requested. Can be
enabled or any other value to disable
this option

android.nonconsumable

Comma delimited string of items that are

non-consumable in the in-app-purchase
API

android.removeBasePermissions

Boolean true/false defaults to false.

Disables the builtin permissions
specifically INTERNET permission (i.e.
no networking)

android.blockExternalStoragePermission Boolean true/false defaults to false.

Disables the external storage (SD card)
permission
android.min_sdk_version

The minimum SDK required to run this

app, the default value changes based
on functionality but can be as low as 7.
This corresponds to the XML attribute
android:minSdkVersion .

android.smallScreens

Boolean true/false defaults

to true. Corresponds to the
android:smallScreens XML

attribute and allows disabling the support

for very small phones
android.xapplication_attr

Allows injecting additional attributes into

the application` tag in the Android
XML

android.xactivity

Allows injecting additional attributes into

the activity tag in the Android XML

android.streamMode

The mode in which the volume key

should behave, defaults to OS default.
Allows setting it to music for music
playback apps

570

Advanced Topics/Under The Hood

Name

Description

android.pushVibratePattern

Comma delimited long values to

describe the push pattern of vibrate used
for the setVibrate native method

android.enableProguard

Boolean true/false defaults to true.

Allows disabling the proguard
obfuscation even on release builds,
notice that this isnt recommended

android.proguardKeep

Arguments for the keep option in

proguard allowing us to keep a
pattern of files e.g. -keep class

com.mypackage.ProblemClass
{ *; }
android.sharedUserId

Allows adding a manifest attribute for the

sharedUserId option

android.sharedUserLabel

Allows adding a manifest attribute for the

sharedUserLabel option

android.targetSDKVersion

Indicates the Android SDK used to

compile the Android build currently
defaults to 21. Notice that not all targets
will work since the source might have
some limitations and not all SDK targets
are installed on the build servers.

android.theme

Light or Dark defaults to Light. On

Android 4+ the default Holo theme is
used to render the native widgets in
some cases and this indicates whether
holo light or holo dark is used. Currently
this doesnt affect the Codename One
theme but that might change in the
future.

android.web_loading_hidden

true/false defaults to false - set to true to

hide the progress indicator that appears
when loading a web page on Android.

block_server_registration

true/false flag defaults to false. By

default Codename One applications

571

Advanced Topics/Under The Hood

Name

Description
register with our server, setting this
to true blocks them from sending
information to our cloud. We keep this
data for statistical purposes and intend
to provide additional installation stats in
the future.

facebook.appId

The application ID for an app that

requires native Facebook login
integration, this defaults to null which
means native Facebook support
shouldnt be in the app

ios.bitcode

true/false defaults to false. Enables

bitcode support for the build.

ios.keyboardOpen

Flips between iOS keyboard open mode

and auto-fold keyboard mode. Defaults
to true which means the keyboard will
remain open and not fold automatically
when editing moves to another field.

ios.urlScheme

Allows intercepting a
URL call using the syntax
<string>urlPrefix<string>

ios.project_type

one of ios, ipad, iphone (defaults to ios).

Indicates whether the resulting binary is
targeted to the iphone only or ipad only.
Notice that the IDE plugin has a "Project
Type" combo box you should use under
the iOS section.

ios.statusbar_hidden

true/false defaults to false. Hides the iOS

status bar if set to true.

ios.newStorageLocation

true/false defaults to false but defined

on new projects as true by default.
This changes the storage directory on
iOS from using caches to using the
documents directory which is more

572

Advanced Topics/Under The Hood

Name

Description
correct but might break compatibility.
1
This is described in this issue

ios.prerendered_icon

true/false defaults to false. The iOS build

process adapts the submitted icon for
iOS conventions (adding an overlay)
that might not be appropriate on some
icons. Setting this to true leaves the icon
unchanged (only scaled).

ios.application_exits

true/false (defaults to false). Indicates

whether the application should exit
immediately on home button press. The
default is to exit, leaving the application
running is only partially tested at the
moment.

ios.themeMode

default/legacy/modern/auto (defaults
to default). Default means you dont
define a theme mode. Currently this
is equivalent to legacy. In the future
we will switch this to be equivalent to
auto. legacy - this will behave like iOS 6
regardless of the device you are running
on. modern - this will behave like iOS 7
regardless of the device you are running
on. auto - this will behave like iOS 6
on older devices and iOS 7 on newer
devices.

ios.interface_orientation

UIInterfaceOrientationPortrait by
default. Indicates the orientation, one
or more of (separated by colon :):
UIInterfaceOrientationPortrait,
UIInterfaceOrientationPortraitUpsideDown,
UIInterfaceOrientationLandscapeLeft,
UIInterfaceOrientationLandscapeRight.
Notice that the IDE plugin has an

https://github.com/codenameone/CodenameOne/issues/1480

573

Advanced Topics/Under The Hood

Name

Description
"Interface Orientation" combo box you
should use under the iOS section.

ios.xcode_version

The version of xcode used on the server.

Defaults to 4.5; currently accepts 5.0 as
an option and nothing else.

java.version

Valid values include 5 or 8. Indicates

the JVM version that should be used
for server compilation, this is defined by
default for newly created apps based on
the Java 8 mode selection

javascript.inject_proxy

true/false (defaults to true ) By default,

the build server will configure the .war
version of your app to use the bundled
proxy servlet for HTTP requests (to
get around same-origin restrictions
on network requests). Setting this to
false prevents this, causing the
application to make network requests
without a proxy.

javascript.minifying

true/false (defaults to true ). By

default the javascript code is minified
to reduce file size. You may optionally
disable minification by setting
javascript.minifying to false .

javascript.proxy.url

The URL to the proxy servlet that should

be used for making network requests.
If this is omitted, the .war version of
the app will be set to use the bundled
proxy servlet, and the .zip version of
the app will be set to use no proxy.
If javascript.inject_proxy is
false , this build-hint will be ignored.

javascript.sourceFilesCopied

true/false (defaults to false ). Setting

this flag to true will cause available
java source files to be included in the

574

Advanced Topics/Under The Hood

Name

Description
resulting .zip and .war files. These may
be used by Chrome during debugging.

javascript.stopOnErrors

true/false (defaults to true ). Cause

javascript build to fail if there are
warnings during the build. In some
cases build warnings wont affect the
running of the app. E.g. if the Javascript
port is missing a method that the app
depends on, but it isnt used in most of
the app. Or if there is multithreaded code
detected in static initializers, but that
code-path isnt used by the app. Setting
this to false may allow you to get
past some build errors, but it might just
result in runtime errors later on, which
are much more difficult to debug. *This
build hint is only available in Codename
One 3.4 and later.

javascript.teavm.version

(Optional) The version of TeaVM to use

for the build. Use caution, only use this
property if you know what you are doing!

rim.askPermissions

true/false defaults to true. Indicates

whether the user is prompted for
permissions on Blackberry devices.

google.adUnitId

Allows integrating Admob/Google Play

2
ads into the application see this

rim.ignor_legacy

true/false defaults to false. When set to

true the Blackberry build targets only
5.0 devices and newer and doesnt build
the 4.x version. rim.nativeBrowser true/
false defaults to false. Enables the native
blackberry browser on OS 5 or higher.
It is disabled by default since it might
casue crashes on some cases.

https://www.codenameone.com/blog/adding-google-play-ads.html

575

Advanced Topics/Under The Hood

Name

Description

rim.obfuscation

true/false defaults to false. Obfuscate the

JAR before invoking the rimc compiler.

ios.plistInject

entries to inject into the iOS plist file

during build.

ios.includePush

true/false (defaults to false). Whether to

include the push capabilities in the iOS
build. Notice that the IDE plugin has an
"Include Push" check box you should
use under the iOS section.

ios.newPipeline

Boolean true/false defaults to true.

Allows toggling the OpenGL ES 2.0
drawing pipeline off to the older OGL ES
1.0 pipeline.

ios.headphoneCallback

Boolean true/false defaults to

false. When set to true it assumes
the main class has two methods:
headphonesConnected &
headphonesDisconnected which it
invokes appropriately as needed

ios.facebook_permissions

Permissions for Facebook used in the

Android build target, applicable only if
Facebook native integration is used.

ios.applicationDidEnterBackground

Objective-C code that can be injected

into the iOS callback method (message)
applicationDidEnterBackground .

ios.enableAutoplayVideo

Boolean true/false defaults to false.

Makes videos "auto-play" when loaded
on iOS

ios.googleAdUnitId

Allows integrating admob/google play

ads, this is effectively identical to
google.adUnitId but only applies to iOS

ios.viewDidLoad

Objective-C code that can be injected

into the iOS callback method (message)
viewDidLoad

576

Advanced Topics/Under The Hood

Name

Description

ios.googleAdUnitIdPadding

Indicates the amount of padding to pass

to the Google ads placed at the bottom
of the screen with google.adUnitId

ios.enableBadgeClear

Boolean true/false defaults to true.

Clears the badge value with every
load of the app, this is useful if the app
doesnt manually keep track of number
values for the badge

ios.glAppDelegateHeader

Objective-C code that can be injected

into the iOS app delegate at the top
of the file. E.g. if you need to include
headers or make special imports for
other injected code

ios.glAppDelegateBody

Objective-C code that can be injected

into the iOS app delegate within the
body of the file before the end. This only
makes sence for methods that arent
already declared in the class

ios.beforeFinishLaunching

Objective-C code that can be

injected into the iOS app delegate
at the top of the body of the
didFinishLaunchingWithOptions callback
method

ios.afterFinishLaunching

Objective-C code that can be

injected into the iOS app delegate
at the bottom of the body of the
didFinishLaunchingWithOptions callback
method

ios.locationUsageDescription

This flag is required for iOS 8 and newer

if you are using the location API. It needs
to include a description of the reason
for which you need access to the users
location

577

Advanced Topics/Under The Hood

Name

Description

ios.add_libs

A semicolon separated list of libraries

that should be linked to the app in order
to build it

ios.pods

A comma separated list of Cocoa Pods

that should be linked to the app in
order to build it. E.g. AFNetworking

~> 2.6, ORStackView ~> 3.0,

SwiftyJSON ~> 2.3
ios.bundleVersion

Indicates the version number of the

bundle, this is useful if you want to
create a minor version number change
for the beta testing support

ios.objC

Added the -ObjC compile flag to the

project files which some native libraries
require

ios.testFlight

Boolean true/false defaults to false and

works only for pro accounts. Enables the
testflight support in the release binaries
for easy beta testing. Notice that the IDE
plugin has a "Test Flight" check box you
should use under the iOS section.

desktop.width

Width in pixels for the form in desktop

builds, will be doubled for retina grade
displays. Defaults to 800.

desktop.height

Height in pixels for the form in desktop

builds, will be doubled for retina grade
displays. Defaults to 600.

desktop.adaptToRetina

Boolean true/false defaults to true. When

set to true some values will ve implicitly
doubled to deal with retina displays and
icons etc. will use higher DPIs

https://cocoapods.org/

578

Advanced Topics/Under The Hood

Name

Description

desktop.resizable

Boolean true/false defaults to true.

Indicates whether the UI in the desktop
build is resizable

desktop.fontSizes

Indicates the sizes in pixels for the

system fonts as a comma delimited
string containing 3 numbers for
small,medium,large fonts.

desktop.theme

Name of the theme res file to use as

the "native" theme. By default this is
native indicating iOS theme on Mac
and Windows Metro on Windows. If its
something else then the app will try to
load the file /themeName.res.

desktop.themeMac

Same as desktop.theme but specific

to Mac OS

desktop.themeWin

Same as desktop.theme but specific

to Windows

desktop.windowsOutput

Can be exe or msi depending on desired

results

noExtraResources

true/false (defaults to false). Blocks

codename one from injecting its own
resources when set to true, the only
effect this has is in slightly reducing
archive size. This might have adverse
effects on some features of Codename
One so it isnt recommended.

j2me.iconSize

Defaults to 48x48. The size of the icon in

the format of width x height (without the
spacing).

14.2.The Architecture Of The Old GUI Builder

We are in the process of replacing the GUI builder with a new GUI
builder that has a more conventional architecture. However, the
old GUI builder is still supported and this section is left "as is" for
reference.
579

Advanced Topics/Under The Hood

The Codename One GUI builder has several unique underlying concepts that arent as
common among such tools, in this article I will try to clarify some of these basic ideas.

14.2.1.Basic Concepts
The Codename One Designer isnt a standard code generator; the UI is saved within the
resource file and can be designed without the source files available. This has several
advantages:
1. No fragile generated code to break.
2. Designers who dont know Java can use the tool.
3. The "Codename One LIVE!" application can show a live preview of your design as
you build it.
4. Images and theme settings can be integrated directly with the GUI without concern.
5. The tool is consistent since the file you save is the file you run.
6. GUIs/themes can be downloaded dynamically without replacing the application
(this can reduce download size).
7. It allows for control over application flow. It allows preview within the tool without
compilation.
This does present some disadvantages and oddities:
1. Its harder to integrate custom code into the GUI builder/designer tool.
2. The tool is somewhat opaque; there is no "code" you can inspect to see what was
accomplished by the tool.
3. If the resource file grows too large it can significantly impact memory/performance
of a running application.
4. Binding between code and GUI isnt as intuitive and is mostly centralized in a single
class.
In theory you dont need to generate any code, you can load any resource file that
contains a UI element as you would normally load a Resource file:
Resources r = Resources.open("/myFile.res");

580

Advanced Topics/Under The Hood

4

Then you can just create a UI using the UIBuilder API:

UIBuilder u = new UIBuilder();

Container c = u.createContainer(r, "uiNameInResource");

5

(Notice that since Form & Dialog both derive from Container you can just downcast
to the appropriate type).
This would work for any resource file and can work completely dynamically! E.g. you
can download a resource file on the fly and just show the UI that is within the resource
8
file That is what Codename One LIVE! is doing internally.

14.2.2.IDE Bindings
While the option of creating a Resource file manually is powerful, its not nearly as
convenient as modern GUI builders allow. Developers expect the ability to override
events and basic behavior directly from the GUI builder and in mobile applications even
the flow for some cases.
To facilitate IDE integration we decided on using a single Statemachine class,
similar to the common controller pattern. We considered multiple classes for every
form/dialog/container and eventually decided this would make code generation more
cumbersome.
The designer effectively generates one class StatemachineBase which is a
9
subclass of UIBuilder (you can change the name/package of the class in the
Codename One properties file at the root of the project). StatemachineBase is
generated every time the resource file is saved assuming that the resource file is within
the src directory of a Codename One project. Since the state machine base class is
always generated, all changes made into it will be overwritten without prompting the
user.
10

User code is placed within the Statemachine class, which is a subclass of the
11
Statemachine Base class. Hence it is a subclass of UIBuilder !
4
5

https://www.codenameone.com/javadoc/com/codename1/ui/util/UIBuilder.html
https://www.codenameone.com/javadoc/com/codename1/ui/Form.html

6
https://www.codenameone.com/javadoc/com/codename1/ui/Dialog.html
7
https://www.codenameone.com/javadoc/com/codename1/ui/Container.html
8
https://www.codenameone.com/codename-one-live.html
9
https://www.codenameone.com/javadoc/com/codename1/ui/util/UIBuilder.html
10
https://www.codenameone.com/javadoc/com/codename1/facebook/User.html
11
https://www.codenameone.com/javadoc/com/codename1/ui/util/UIBuilder.html

581

Advanced Topics/Under The Hood

When the resource file is saved the designer generates 2 major types of methods into
StatemachineBase :
1. Finders - findX(Container c) . Finders are shortcut methods that allow us to

find a component instance within the container hierarch. Effectively this is a shortcut
syntax for UIBuilder.findByName() , its still useful since the method is type
safe. Hence if a resource component name is changed the find() method will fail
in subsequent compilations.
12

2. Callback
events - these are various callback methods with common names
e.g.: onCreateFormX() , beforeFormX() etc. These will be invoked when a
particular event/behavior occurs.
Within the GUI builder, the event buttons would be enabled and the GUI builder
provides a quick and dirty way to just override these methods. To prevent a future case
in which the underlying resource file will be changed (e.g formX could be renamed to
formY) a super method is invoked e.g. super. onCreateFormX() ;
This will probably be replaced with the @Override annotation when Java 5 features
are integrated into Codename One.

14.2.3.Working With The Generated Code

The generated code is rather simplistic, e.g. the following code from the tzone demo
adds a for the remove button toggle:
protected void onMainUI_RemoveModeButtonAction(Component c, ActionEvent
event) {

// If the resource file changes the names of components this call will

break notifying you that you should fix the code

super.onMainUI_RemoveModeButtonAction(c, event);

removeMode = !removeMode;
Container friendRoot = findFriendsRoot(c.getParent());
Dimension size = null;
if(removeMode) {
{

if(Display.getInstance().getDeviceDensity() > Display.DENSITY_LOW)

findRemoveModeButton(c.getParent()).setText("Finish");

} else {

size = new Dimension(0, 0);

12

https://www.codenameone.com/javadoc/com/codename1/util/Callback.html

582

Advanced Topics/Under The Hood

if(Display.getInstance().getDeviceDensity() > Display.DENSITY_LOW)

findRemoveModeButton(c.getParent()).setText("Remove");

for(int iter = 0 ; iter < friendRoot.getComponentCount() ; iter++) {

Container currentFriend =
(Container)friendRoot.getComponentAt(iter);
currentFriend.setShouldCalcPreferredSize(true);
currentFriend.setFocusable(!removeMode);
findRemoveFriend(currentFriend).setPreferredSize(size);
currentFriend.animateLayout(800);
}

As you can see from the code above implementing some basic
callbacks within the state machine is rather simple. The method
findFriendsRoot(c.getParent()); is used to find the "FriendsRoot"
component within the hierarchy, notice that we just pass the parent container to the
finder method. If the finder method doesnt find the friend root under the parent it will
find the "true" root component and search there.
The friends root is a container that contains the full list of our "friends" and within
it we can just work with the components that were instantiated by the GUI builder.
Implementing Custom Components There are two basic approaches for custom
components:
1. Override a specific type - e.g. make all Forms derive a common base class.
2. Replace a deployed instance.
The first uses a feature of UIBuilder

13

which allows overriding component types,

specifically override createComponentInstance to return an instance of your desired

component e.g.:
protected Component createComponentInstance(String componentType, Class
cls) {

if(cls == Form.class) {
}

return new MyForm();

return super.createComponentInstance(componentType, cls);

13

https://www.codenameone.com/javadoc/com/codename1/ui/util/UIBuilder.html

583

Advanced Topics/Under The Hood

}

This code allows me to create a unified global form subclass. Thats very useful when I
want so global system level functionality that isnt supported by the designer normally.
The second approach allows me to replace an existing component:
protected void beforeSplash(Form f) {
super.beforeSplash(f);

splashTitle = findTitleArea(f);
// create a "slide in" effect for the title
dummyTitle = new Label();

dummyTitle.setPreferredSize(splashTitle.getPreferredSize());
f.replace(splashTitle, dummyTitle, null);

protected void postSplash(Form f) {

super.postSplash(f);

f.replace(dummyTitle, splashTitle,
CommonTransitions.createSlide(CommonTransitions.SLIDE_VERTICAL,
true, 1000));
splashTitle = null;
dummyTitle = null;

Notice that we replace the title with an empty label; in this case we do this so we can later
replace it while animating the replace behavior thus creating a slide-in effect within the
title. It can be replaced though, for every purpose including the purpose of a completely
different custom made component. By using the replace method the existing layout
constraints are automatically maintained.

14.3.Android Permissions
One of the annoying tasks when programming native Android applications is tuning all
the required permissions to match your codes requirements, Codename One aims to
simplify this. The build server automatically introspects the classes sent to it as part of
the build and injects the right set of permissions required by the app.
However, sometimes developers might find the permissions that come up a bit
confusing and might not understand why a specific permission came up. This maps
584

Advanced Topics/Under The Hood

Android permissions to the methods/classes in Codename One that would trigger them.
Notice that this list isnt exhaustive as the API is rather large:
android.permission.WRITE_EXTERNAL_STORAGE - this permission appears by
default for Codename One applications, since the FileSystemStorage API (which
is used extensively) might have some dependencies on it. You can explicitly disable it
using the build hint android.blockExternalStoragePermission=true , notice
that this is something we dont test and it might fail on devices.

android.permission.INTERNET - this is a hardcoded permission in Codename

One, the ability to connect to the network is coded into all Codename One applications.
android.hardware.camera & android.permission.RECORD_AUDIO - are
triggered by com.codename1.Capture
android.permission.RECORD_AUDIO
MediaManager.createMediaRecorder()
Display.createMediaRecorder()

is

triggered

by

usage

of
&

android.permission.READ_PHONE_STATE
is
triggered
by
com.codename1.ads
package,
com.codename1.components.Ads ,
com.codename1.components.ShareButton ,
com.codename1.media ,
com.codename1.push , Display.getUdid() & Display.getMsisdn() . This
permission is required for media in order to suspend audio playback when you get a
phone call.
android.hardware.location ,
android.hardware.location.gps ,
android.permission.ACCESS_FINE_LOCATION ,
android.permission.ACCESS_MOCK_LOCATION
&
android.permission.ACCESS_COARSE_LOCATION
map
to
com.codename1.maps & com.codename1.location .
package.permission.C2D_MESSAGE ,
com.google.android.c2dm.permission.RECEIVE ,
android.permission.RECEIVE_BOOT_COMPLETED - are requested by the
com.codename1.push package
android.permission.READ_CONTACTS
triggers
by
the
com.codename1.contacts & Display.getAllContacts() .

package

android.permission.VIBRATE - is triggered by Display.vibrate() and

Display.notifyStatusBar()
585

Advanced Topics/Under The Hood

android.permission.SEND_SMS - is triggered by Display.sendSMS()
android.permission.WAKE_LOCK - is triggered by Display.lockScreen() &
Display.setScreenSaverEnabled()
android.permission.WRITE_CONTACTS
Display.createContact() ,
ContactsManager.createContact()
ContactsManager.deleteContact()

is
triggered
by
Display.deleteContact() ,
&

14.3.1.Permissions Under Marshmallow (Android 6+)

Starting with Marshmallow (Android 6+ API level 23) Android shifted to a permissions
system that prompts users for permission the first time an API is used e.g. when
accessing contacts the user will receive a prompt whether to allow contacts access.
Permission can be denied and a user can later on revoke/grant a
permission via external settings UI
This is really great as it allows apps to be installed with a single click and no permission
prompt during install which can increase conversion rates!

Enabling Permissions
Codenmae One compiles Android targets with SDK level 23 but not with target level 23!
This means that by default the new permission mode is still off and you wont see any
of the effects mentioned below.
This will probably change to the default in the future but at the
moment the target SDK defaults to 21
To activate this functionality you will need to set the target SDK to level 23 by using the
android.targetSDKVersion=23 build hint.

Permission Prompts
To test this API see the following simple contacts app:
Form f = new Form("Contacts", BoxLayout.y());

586

Advanced Topics/Under The Hood

f.add(new InfiniteProgress());

Display.getInstance().invokeAndBlock(() -> {
Contact[] ct = Display.getInstance().getAllContacts(true, true, false,
true, true, false);
Display.getInstance().callSerially(() -> {
f.removeAll();
for(Contact c : ct) {

MultiButton mb = new MultiButton(c.getDisplayName());

mb.setTextLine2(c.getPrimaryPhoneNumber());
f.add(mb);

});

});

}
f.revalidate();

f.show();

When we try to install this app without changing anything on an Android 6 device we
see this UI:

587

Advanced Topics/Under The Hood

Figure 14.5. Install UI when using

the old permissions system
588

Advanced Topics/Under The Hood

When we set android.targetSDKVersion=23 in the build hints and try to install
again the UI looks like this:

589

Advanced Topics/Under The Hood

Figure 14.6. Install UI when using

the new permissions system
590

Advanced Topics/Under The Hood

When we launch the UI under the old permissions system we see the contacts instantly.
In the new system we are presented with this UI:

591

Advanced Topics/Under The Hood

Figure 14.7. Native permission prompt

first time
592

Advanced Topics/Under The Hood

If we accept and allow all is good and the app loads as usual but if we deny then
Codename One gives the user another chance to request the permission. Notice that
in this case you can customize the prompt string as explained below.

593

Advanced Topics/Under The Hood

Figure 14.8. Codename One permission

prompt
594

Advanced Topics/Under The Hood

If we select dont ask then you will get a blank screen since the contacts will return as
a 0 length array. This makes sense as the user is aware he denied permission and
the app will still function as expected on a device where no contacts are available.
However, if the user realizes his mistake he can double back and ask to re-prompt for
permission in which case he will see this native prompt:

595

Advanced Topics/Under The Hood

Figure 14.9. Native permission prompt

second time
596

Advanced Topics/Under The Hood

Notice that denying this second request will not trigger another Codename One prompt.

Code Changes
There are no explicit code changes needed for this functionality to "just work". The
respective APIs will work just like they always worked and will prompt the user
seamlessly for permissions.
Some behaviors that never occurred on Android but were perfectly
legal in the past might start occurring with the switch to the new API.
E.g. the location manager might be null and your app must always
be ready to deal with such a situation
When permission is requested a user will be seamlessly prompted/warned, Codename
One has builtin text to control such prompts but you might want to customize the text.
You can customize permission text via the Display properties e.g. to customize the
text of the contacts permission we can do something such as:
Display.getInstance().setProperty("android.permission.READ_CONTACTS", "MyCoolChatApp
needs access to your contacts so we can show you which of your friends
already have MyCoolChatApp installed");

This is optional as there is a default value defined. You can define this once in the
init(Object) method but for some extreme cases permission might be needed for
different things e.g. you might ask for this permission with one reason at one point in
the app and with a different reason at another point in the app.
The
following
permission
"android.permission.READ_PHONE_STATE"

keys

are

supported:

android.permission.WRITE_EXTERNAL_STORAGE ,
android.permission.ACCESS_FINE_LOCATION ,
android.permission.SEND_SMS , android.permission.READ_CONTACTS ,
android.permission.WRITE_CONTACTS ,
android.permission.RECORD_AUDIO .

Simulating Prompts
You can simulate permission prompts by checking that option in the simulator menu.

597

Advanced Topics/Under The Hood

Figure 14.10. Simulate permission prompts menu item in the

simulator
This will produce a dialog to the user whenever this happens in Android and will try to
act in a similar way to the device. Notice that you can test it in the iOS simulator too.

AndroidNativeUtils checkForPermission
If you write Android native code using native interfaces you are probably familiar
with the AndroidNativeUtil class from the com.codename1.impl.android
package.
This class provides access to many low level capabilities you would need as a
developer writing native code. Since native code might need to request a permission
we introduced the same underlying logic we used namely: checkForPermission .
To get a permission you can use this code as such:
if(!

com.codename1.impl.android.AndroidNativeUtil.checkForPermission(Manifest.permission.READ
should be the description shown to the user...")){
}

// you didn't get the permission, you might want to return here

// you have the permission, do what you need

This will prompt the user with the native UI and later on with the fallback option
as described above. Notice that the checkForPermission method is a blocking
method and it will return when there is a final conclusion on the subject. It uses
598

Advanced Topics/Under The Hood

invokeAndBlock and can be safely invoked on the event dispatch thread without
concern.

14.4.On Device Debugging

Codename One supports debugging applications on devices by using the natively
generated project. All paid subscription levels include the ability to check an Include
Source flag in the settings that returns a native OS project. You can debug that project
in the respective native IDE.
In iOS this is usually strait forward, just open the project with xcode and run it optionally
disabling bitcode.
With Android Studio this is sometimes as very easy task as it is possible to actually
open the gradle project in Android Studio and just run it. However, due to the fragile
nature of the gradle project this stopped working for some builds and has been "flaky".

14.4.1.Android Studio Debugging (Easy Way)

By default you should be able to open the gradle project in Android Studio and just run
it. To get this to work open the Android Studio Setting and select gradle 2.11.

Figure 14.11. Gradle settings UI in Android Studio (notice you need

gradle 2.11 and not 2.8 as pictured here)
599

Advanced Topics/Under The Hood

If this works for you then you can ignore the section below.

14.4.2.Android Studio Debugging the Hard Way

In some cases the gradle project might not work or this might fail with a change from
Google.
Here are steps that should work for everyone:
1. Check the include source flag in the IDE and send a build
2. Download the sources.zip result from the build server
3. Launch Android Studio and create a new project
4. Make sure to use the same package and app name as you did in the Codename
One project, select to not create an activity
5. Unzip the sources.zip file and copy the main directory from its src
directory to the Android Studio projects src directory make sure to overwrite files/
directories.
6. Copy its libs directory on top of the existing libs
7. Copy the source gradle dependencies content to the destination gradle file
8. Connect your device and press the Debug button for the IDE
You might need to copy additional gradle file meta-data such as
multi-dexing etc.
You might not need to repeat the whole thing with every build. E.g. it might be practical
to only copy the userSources.jar from the libs directory to get the latest version of
your code. You can copy the src/main directory to get the latest up to date Android
port.

14.5.Native Interfaces
Sometimes you may wish to use an API that is unsupported by Codename One or
integrate with a 3rd party library/framework that isnt supported. These are achievable
tasks when writing native code and Codename One lets you encapsulate such native
code using native interfaces.
Notice that when we say "native" we do not mean C/C++ always but rather the platforms
"native" environment. So in the case of Android the Java code will be invoked with full
access to the Android API, in case of iOS an Objective-C message would be sent and
so forth.
600

Advanced Topics/Under The Hood

You can still access C code under Android either by using JNI from
the Android native code or by using a library
Native interfaces are designed to only allow primitive types, Strings, arrays of
14
primitive types (single dimension only) & PeerComponent values. Any other type of
parameter/return type is prohibited. However, once in the native layer the native code
can act freely and query the Java layer for additional information.
The reason for the limits is the disparity between the platforms.
Mapping a Java Object to an Objective-C NSObject is possible
but leads to odd edge cases and complexity e.g. GC vs. ARC in a
disparate object graph
Furthermore, native methods should avoid features such as overloading, varargs (or
any Java 5+ feature for that matter) to allow portability for languages that do not support
such features.
Do not rely on pass by reference/value behavior since they vary
between platforms
Implementing a native layer effectively means:
15

1. Creating an interface that extends NativeInterface and only defines methods with
the arguments/return values declared in the previous paragraph.
2. Creating the proper native implementation hierarchy based on the call conventions
for every platform within the native directory
E.g. to create a simple hello world interface do something like:
package com.mycompany.myapp;

import com.codename1.system.NativeInterface;

public interface MyNative extends NativeInterface {

}

String helloWorld(String hi);

We now need to right click the class in the IDE and select the Generate Native Access
menu item:
14
15

https://www.codenameone.com/javadoc/com/codename1/ui/PeerComponent.html
https://www.codenameone.com/javadoc/com/codename1/system/NativeInterface.html

601

Advanced Topics/Under The Hood

Figure 14.12. Generating the native code

Figure 14.13. Once generated we are prompted that the native code
is in the "native" directory
We can now look int the native directory in the project root (in NetBeans you can see
that in the Files tab) and you can see something that looks like this:

602

Advanced Topics/Under The Hood

Figure 14.14. Native directory structure containing stubs for the

various platforms
These are effectively stubs you can edit to implement the methods in native code.

603

Advanced Topics/Under The Hood

If you re-run the Generate Native Access tool you will get this dialog,
if you answer yes all the files will be overwritten, if you answer no
only files you deleted/renamed will be recreated

Figure 14.15. Running "Generate Native Access" when some/all of

the native files exist already
For now lets leave the stubs and come back to them soon. From the Codename One
Java code we can call the implementation of this native interface using:
MyNative my = NativeLookup.create(MyNative.class);
if(my != null && my.isSupported()) {
}

Log.p(my.helloWorld("Hi"));

Notice that for this to work you must implement the native code on all supported
platforms.
Well start with Android which should be familiar and intuitive to many developers, this
is how the generated file under the native/android directory looks:
package com.mycompany.myapp;
public class MyNativeImpl {

public String helloWorld(String param) {

}

return null;

public boolean isSupported() {

}

return false;

604

Advanced Topics/Under The Hood

The stub implementation always returns false , null or 0 by default.
The isSupported also defaults to false thus allowing us to implement a

NativeInterface on some platforms and leave the rest out without really knowing
anything about these platforms.
We can implement the Android version using code similar to this:
package com.mycompany.myapp;
import android.util.Log;
public class MyNativeImpl {
public String helloWorld(String param) {
Log.d("MyApp", param);

return "Tada";

public boolean isSupported() {

return true;

Notice that we are using the Android native android.util.Log class which
isnt accessible from standard Codename One code
The impl class doesnt physically implement the MyNative interface!
This is intentional and due to the PeerComponent functionality mentioned
below. You dont need to add an implements clause.
Notice that there is no constructor and the class is public. It is crucial that the
system will be able to allocate the class without obstruction. You can use a
constructor but it cant have any arguments and you shouldnt rely on semantics
of construction.
We implemented the native method and that we set isSupported to true.
The IDE wont provide completion suggestions and will claim that
there are errors in the code!
Codename One doesnt include the native platforms in its bundle
e.g. the full Android SDK or the full xcode Objective-C runtime.
However, since the native code is compiled on the servers (where
these runteims are present) this shouldnt be a problem

605

Advanced Topics/Under The Hood

When implementing a non-trivial native interface, send a server
build with the "Include Source" option checked. Implement the native
interface in the native IDE then copy and paste the native code back
into Codename One
The implementation of this interface is nearly identical for Android, J2ME & Java SE.

14.5.1.Objective-C (iOS)
When generating the Objective-C code the "Generate Native Sources"
tool produces two files:
com_mycompany_myapp_MyNativeImpl.h
&
com_mycompany_myapp_MyNativeImpl.m .
The
.m
files are the Objective-C equivalent
.h
files contain the header/include information.
com_mycompany_myapp_MyNativeImpl.h contains:

of
In

#import <Foundation/Foundation.h>
@interface com_mycompany_myapp_MyNativeImpl : NSObject {
}
-(NSString*)helloWorld:(NSString*)param;
-(BOOL)isSupported;
@end

And com_mycompany_myapp_MyNativeImpl.m contains:

#import "com_mycompany_myapp_MyNativeImpl.h"
@implementation com_mycompany_myapp_MyNativeImpl
-(NSString*)helloWorld:(NSString*)param{
return nil;
}
-(BOOL)isSupported{
return NO;
}
@end

606

.c
this

files
case

and
the

Advanced Topics/Under The Hood

Objective-C relies on argument names as part of the
message (method) signature. So -(NSString*)helloWorld:
(NSString*)param
isnt
the
same
as
(NSString*)helloWorld:
(NSString*)iChangedThisName !
Dont change argument names in the Objective-C native interface!
Here is a simple implementation similar to above:
#import "com_mycompany_myapp_MyNativeImpl.h"
@implementation com_mycompany_myapp_MyNativeImpl
-(NSString*)helloWorld:(NSString*)param{
NSLog(@"MyApp: %@", param);
}

return @"Tada";

-(BOOL)isSupported{
return YES;
}
@end

14.5.2.Javascript
Native interfaces in Javascript look a little different than the other platforms since
Javascript doesnt natively support threads or classes. The native implementation
should be placed in a file with name matching the name of the package and the class
name combined where the "." elements are replaced by underscores.
The default generated stubs for
com_mycompany_myapp_MyNative :

the

JavaScript

build

look

(function(exports){
var o = {};
o.helloWorld__java_lang_String = function(param1, callback) {
};

callback.error(new Error("Not implemented yet"));

607

like

this

Advanced Topics/Under The Hood

o.isSupported_ = function(callback) {
};

callback.complete(false);

exports.com_mycompany_myapp_MyNative= o;
})(cn1_get_native_interfaces());

A simple implementation looks like this.

(function(exports){
var o = {};
o.helloWorld__java_lang_String = function(param1, callback) {
}

callback.complete("Hello World!!!");

o.isSupported_ = function(callback) {
};

callback.complete(true);

exports.com_my_code_MyNative = o;
})(cn1_get_native_interfaces());

Notice that we use the complete() method of the provided callback to pass the
return value rather than using the return statement. This is to work around the
fact that Javascript doesnt natively support threads. The Java thread that is calling
your native interface will block until your method calls callback.complete() . This
allows you to use asynchronous APIs inside your native method while still allowing
Codename One to work use your native interface via a synchronous API.
Make sure you call either callback.complete() or
callback.error() in your method at some point, or you will
cause a deadlock in your app (code calling your native method will
just sit and "wait" forever for your method to return a value).
The naming conventions for the methods themselves are modeled after the naming
conventions shown in the previous examples:
<method-name>__<param-1-type>_<param-2-type>_<param-n-type>
608

Advanced Topics/Under The Hood

Where <method-name> is the name of the method in Java, and the `<param-Xtype>`s are a string representing the parameter type. The general rule for these strings
are:
1. Primitive types are mapped to their type name. (E.g. int to "int", double to
"double", etc).
2. Reference types are mapped to their fully-qualified class name with '.' replaced with
underscores. E.g. java.lang.String would be "java_lang_String".
3. Array parameters are marked by their scalar type name followed by an underscore
and "1ARRAY". E.g. int[] would be "int_1ARRAY" and String[] would be
"java_lang_String_1ARRAY".

JavaScript Examples
Java API:
public void print(String str);

becomes
o.print__java_lang_String = function(param1, callback) {

console.log(param1);
callback.complete();

Java API:
public int add(int a, int b);

becomes
o.add__int_int = function(param1, param2, callback) {
}

callback.complete(param1 + param2);

public int add(int[] a);

609

Advanced Topics/Under The Hood

becomes
o.add__int_1ARRAY = function(param1, callback) {
var c = 0, len = param1.length;
for (var i =0; i<len; i++) {

c += param1[i];
}
callback.complete(c);

14.5.3.Native GUI Components

16

PeerComponent return values are automatically translated to the platform native

peer as an expected return value. E.g. for a NativeInterface method such as this:
public PeerComponent` createPeer();

Android native implementation would use:

public View createPeer() {
}

return null;

The iphone would need to return a pointer to a view e.g.:

- (UIView*)createPeer;

Not all platforms support native peers. Specifically JavaSE doesnt

support them due to the way the JavaSE native interfaces are
mapped to their implementation.
Note that this wont limit the code from running on an unsupported
platform. Only that specific method wont work.
Javascript would expect a DOM Element (e.g. a <div> tag to be returned.). E.g.
o.createHelloComponent_ = function(callback) {
var c = jQuery('<div>Hello World</div>')

16

https://www.codenameone.com/javadoc/com/codename1/ui/PeerComponent.html

610

Advanced Topics/Under The Hood

.css({'background-color' : 'yellow', 'border' : '1px solid

blue'});
callback.complete(c.get(0));
};

Notice that if you want to use a native library (jar, .a file etc.) just places it within the
appropriate native directory and it will be packaged into the final executable. You would
only be able to reference it from the native code and not from the Codename One code,
which means you will need to build native interfaces to access it.
This is discussed further below.

14.5.4.Type Mapping & Rules

Several rules govern the creation of NativeInterfaces and we only briefly covered some
of them.
The implementation class must have a default public constructor or no constructor
at all
Native methods cant throw exceptions, checked or otherwise
A native method cant have the name init as this is a reserved method in
Objective-C
Only the supported types listed below can be used
Native implementations cant rely on pass by reference/value semantics as those
might change between platforms
hashCode , equals & toString are reserved and wont be mapped to native
code

Table 14.2. NativeInterface Supported Types

Java

Android

RIM

JavaSE

Obj-C

C#

byte

byte

byte

byte

char

sbyte

boolean

boolean

boolean

boolean

BOOL

bool

char

char

char

char

int

char

short

short

short

short

short

short

int

int

int

int

int

int

611

Advanced Topics/Under The Hood

Java

Android

RIM

JavaSE

Obj-C

C#

long

long

long

long

long long

long

float

float

float

float

float

float

double

double

double

double

double

double

String

String

String

String

NSString*

String

byte[]

byte[]

byte[]

byte[]

NSSData*

sbyte[]

boolean[]

boolean[]

boolean[]

boolean[]

NSData*

bool[]

char[]

char[]

char[]

char[]

NSData

char[]

short[]

short[]

short[]

short[]

NSData*

short[]

int[]

int[]

int[]

int[]

NSData*

int[]

long[]

long[]

long[]

long[]

NSData*

long[]

float[]

float[]

float[]

float[]

NSData*

float[]

double[]

double[]

double[]

double[]

NSData*

double[]

PeerComponent
android.view.View
net.rim.device.api.ui.Field
PeerComponent
void*

FrameworkElement

JavaScript is excluded from the table above as it isnt a type safe

language and thus has no such type mapping
PeerComponent on iOS is void* but UIView is expected as
a result
The examples below demonstrate the signatures for this method on all platforms:
NativeInterface definition
public void test(byte b, boolean boo, char c, short s, int i, long
l, float f, double d, String ss,

byte[] ba, boolean[] booa, char[] ca, short[] sa, int[] ia, long[]

la, float[] fa, double[] da,

PeerComponent cmp);

Android Version
public void test(byte param, boolean param1, char param2, short

param3, int param4, long param5, float param6, double param7, String
param8, byte[] param9, boolean[] param10, char[] param11, short[]
param12, int[] param13, long[] param14, float[] param15, double[]
param16, android.view.View param17) {

612

Advanced Topics/Under The Hood

}

iOS Version
-(void)test:(char)param param1:(BOOL)param1 param2:(int)param2 param3:
(short)param3 param4:(int)param4 param5:(long long)param5 param6:
(float)param6 param7:(double)param7 param8:(NSString*)param8 param9:
(NSData*)param9 param10:(NSData*)param10 param11:(NSData*)param11 param12:
(NSData*)param12 param13:(NSData*)param13 param14:(NSData*)param14
param15:(NSData*)param15 param16:(NSData*)param16 param17:(void*)param17;
}

JavaScript Version

o.test__byte_boolean_char_short_int_long_float_double_java_lang_String_byte_1ARRAY_boole
= function(param1, param2, param3, param4, param5, param6, param7,

param8, param9, param10, param11, param12, param13, param14, param15,

param16, param17, param18, callback) {
};

callback.error(new Error("Not implemented yet"));

Java SE Version
public void test(byte param, boolean param1, char param2, short

param3, int param4, long param5, float param6, double param7, String
param8, byte[] param9, boolean[] param10, char[] param11, short[]
param12, int[] param13, long[] param14, float[] param15, double[]
param16, com.codename1.ui.PeerComponent param17) {

RIM/Blackberry Version
public void test(byte param, boolean param1, char param2, short

param3, int param4, long param5, float param6, double param7, String
param8, byte[] param9, boolean[] param10, char[] param11, short[]
param12, int[] param13, long[] param14, float[] param15, double[]
param16, net.rim.device.api.ui.Field param17) {

Java ME Version
public void test(byte param, boolean param1, char param2, short

param3, int param4, long param5, float param6, double param7, String
param8, byte[] param9, boolean[] param10, char[] param11, short[]

613

Advanced Topics/Under The Hood

param12, int[] param13, long[] param14, float[] param15, double[]
param16, Object param17) {

C# Version
public void test(byte param, bool param1, char param2, short param3, int
param4, long param5, float param6, double param7, String param8, byte[]
param9, boolean[] param10, char[] param11, short[] param12, int[]
param13, long[] param14, float[] param15, double[] param16,
FrameworkElement param17) {

14.5.5.Android Native Permissions

Normally permissions in Codename One are seamless. Codename One traverses the
bytecode and automatically assigns permissions to Android applications based on the
APIs used by the developer.
However, when accessing native functionality this just wont work since native code
might require specialized permissions and we dont/cant run any serious analysis on
it (it can be just about anything).
So if you require additional permissions in your Android native code you need to define
them in the build arguments using the android.xpermissions build argument and setting
it to your additional permissions e.g.:
android.xpermissions=<uses-permission
android:name="android.permission.READ_CALENDAR" />

You need to include the full XML snippet. You can unify multiple lines
into a single line in the GUI as XML allows that.

14.5.6.Native AndroidNativeUtil
If you do any native interfaces programming in Android you should be familiar with the
AndroidNativeUtil class which allows you to access native device functionality
more easily from the native code. E.g. many Android APIs need access to the
Activity which you can get by calling AndroidNativeUtil.getActivity() .
The native util class includes quite a few other features such as:
614

Advanced Topics/Under The Hood

runOnUiThreadAndBlock(Runnable) - this is such a common pattern
that it was generalized into a public static method. Its identical to
Activity.runOnUiThread but blocks until the runnable finishes execution.
addLifecycleListener / removeLifecycleListener - These essentially
provide you with a callback to lifecycle events: onCreate etc. which can be pretty
useful for some cases.
17

registerViewRenderer - PeerComponent 's are usually shown on top of the

UI since they are rendered within their own thread outside of the EDT cycle. So
18
when we need to show a Dialog on top of the peer we grab a screenshot of the
peer, hide it and then show the dialog with the image as the background (the same
applies for transitions). Unfortunately some components (specifically the MapView)
might not render properly and require custom code to implement the transferal to a
native Bitmap, this API allows you to do just that.
You can work with AndroidNativeUtil using native code such as this:
import com.codename1.impl.android.AndroidNativeUtil;
class NativeCallsImpl {

public void nativeMethod() {

AndroidNativeUtil.getActivity().runOnUiThread(new Runnable() {
public void run() {

});

...

}
....

14.5.7.Native Code Callbacks

Native interfaces standardize the invocation of native code from Codename One, but
it doesnt standardize the reverse of callbacks into Codename One Java code. The
reverse is naturally more complicated since its platform specific and more error prone.
A common "trick" for calling back is to just define a static method and then trigger it
from native code. This works nicely for Android, Java SE, Blackberry & Java ME since
17
18

https://www.codenameone.com/javadoc/com/codename1/ui/PeerComponent.html
https://www.codenameone.com/javadoc/com/codename1/ui/Dialog.html

615

Advanced Topics/Under The Hood

those platforms use Java for their "native code". Mapping this to iOS requires some
basic understanding of how the iOS VM works.
For the purpose of this explanation lets pretend we have a class called NativeCallback
in the src hierarchy under the package com.mycompany that has the method:
public static void callback() .
package com.mycompany;

public class NativeCallback {

public static void callback() {

// do stuff

So if I want to call it from Android or all of the Java based platforms I can just write
this in the "native" code:
com.mycompany.NativeCallback.callback();

I can also pass a argument as we do later on:

com.mycompany.NativeCallback.callback("My Arg");

Accessing Callbacks from Objective-C

If we want to invoke that method from Objective-C we need to do the following.
Add an include statement as such:
#include "com_mycompany_NativeCallback.h"
#include "CodenameOne_GLViewController.h"

Notice that the CodenameOne_GLViewController.h include defines various

macros such as CN1_THREAD_STATE_PASS_SINGLE_ARG .
Then when we want to trigger the method just do:
com_mycompany_NativeCallback_callback__(CN1_THREAD_STATE_PASS_SINGLE_ARG);

The VM passes the thread context along method calls to save on API calls (thread
context is heavily used in Java for synchronization, gc and more).
616

Advanced Topics/Under The Hood

We can easily pass arguments like:
public static void callback(int arg)

Which maps to native as (notice the extra _ before the int):

com_mycompany_NativeCallback_callback___int(CN1_THREAD_GET_STATE_PASS_ARG
intValue);

Notice that there is no comma between the CN1_THREAD_GET_STATE_PASS_ARG

and the value!

Why No Comma?
The comma is included as part of the macro which makes for code that isnt as
readable.
19

The reason for this dates to the migration from XMLVM

to the
current ParparVM implementation. CN1_THREAD_GET_STATE_PASS_ARG
is defined as nothing in XMLVM since it didnt use that concept. Yet under
ParparVM it will include the necessary comma.
A common use case is passing string values to the Java side, or really NSString* which
is iOS equivalent. Assuming a method like this:
public static void callback(String arg)

You would need to convert the NSString* value you already have to a
java.lang.String which the callback expects.
The fromNSString function also needs this special argument so you will need to
modify the method as such:
com_mycompany_NativeCallback_callback___java_lang_String(CN1_THREAD_GET_STATE_PASS_ARG
fromNSString(CN1_THREAD_GET_STATE_PASS_ARG nsStringValue));

And finally you might want to return a value from callback as such:
19

The old Codename One VM

617

Advanced Topics/Under The Hood

public static int callback(int arg)

This is tricky since the method name changes to support covariant return types and
so the signature would be:
com_mycompany_NativeCallback_callback___int_R_int(intValue);

The upper case R allows us to differentiate between void callback(int,int) and

int callback(int) .
Covariant return types are a little known Java 5 feature. E.g.
the method Object getX() can be overriden by MyObject
getX() . However, in the VM level they can both exist side by side.

Accessing Callbacks from Javascript

The mechanism for invoking static callback methods from Javascript (for the Javascript
port only) is similar to Objective-Cs. The this object in your native interface method
contains a property named $GLOBAL$ that provides access to static java methods.
This object will contain Javascript mirror objects for each Java class (though the
property name is mangled by replacing "." with underscores). Each mirror object
contains a wrapper method for its underlying classs static methods where the method
name follows the same naming convention as is used for the Javascript native methods
themselves (and very similar to the naming conventions used in Objective-C).
For example, the Google Maps project includes the static callback method:
static void fireMapChangeEvent(int mapId, final int zoom, final double
lat, final double lon) { ... }

defined in the com.codename1.googlemaps.MapContainer class.

This method is called from Javascript inside a native interface using the following code:
var fireMapChangeEvent = this.$GLOBAL

$.com_codename1_googlemaps_MapContainer.fireMapChangeEvent__int_int_double_double;
google.maps.event.addListener(this.map, 'bounds_changed', function() {
fireMapChangeEvent(self.mapId, self.map.getZoom(),
self.map.getCenter().lat(), self.map.getCenter().lng());
});

618

Advanced Topics/Under The Hood

In this example we first obtain a reference to the fireMapChangeEvent method,
and then call it later. However, we could have called it directly also.
Your code MUST contain the full string path this.$GLOBAL
$.your_class_name.your_method_name or the build server
will not be able to recognize that your code requires this method. The
$GLOBAL$ object is populated by the build server only with those
classes and methods that are used inside your native methods. If
the build server doesnt recognize that the methods are being used
(via this pattern) it wont generate the necessary wrappers for your
Javascript code to access the Java methods.

Asynchronous Callbacks & Threading

One of the problematic aspects of calling back into Java from Javascript is that
Javascript has no notion of multi-threading. Therefore, if the method you are calling
uses Javas threads at all (e.g. It includes a wait() , notify() , sleep() ,
callSerially() , etc) you need to call it asynchronously from Javascript. You
can call a method asynchronously by appending $async to the method name. E.g.
With the Google Maps example above, you would change :
this.$GLOBAL

$.com_codename1_googlemaps_MapContainer.fireMapChangeEvent__int_int_double_double;

to
this.$GLOBAL

$.com_codename1_googlemaps_MapContainer.fireMapChangeEvent__int_int_double_double
$async;

This will cause the call to be wrapped in the appropriate bootstrap code to work properly
with threads - and it is absolutely necessary in cases where the method may use
threads of any kind. The side-effect of calling a method with the $async suffix is that
you cant use return values from the method.
In most cases you should use the async version of a method
when calling it from your native method. Only use the synchronous
(default) version if you are absolutely sure that the method doesnt
use any threading primitives.
619

Advanced Topics/Under The Hood

14.6.Libraries - cn1lib
Support for JAR files in Codename One has been a source of confusion so its probably
a good idea to revisit this subject again and clarify all the details.
The first source of confusion is changing the classpath. You should NEVER change
the classpath or add an external JAR via the IDE classpath UI. The reasoning here is
very simple, these IDEs dont package the JARs into the final executable and even if
they did these JARs would probably use features unavailable or inappropriate for the
device (e.g. java.io.File etc.).

Figure 14.16. Dont change the classpath, this is how it should look
for a typical Java 8 Codename One application
Cn1libs are Codename Ones file format for 3rd party extensions. Its physicially a zip
file containing other zip files and some meta-data.

620

Advanced Topics/Under The Hood

14.6.1.Why Not Use JAR?

A jar can be compiled with usage of any Java API that might not be supported, it can
be compiled with a Java target version that isnt tested.
Jars dont include support for writing native code, you could use JNI in jars (awkwardly)
but that doesnt match Codename Ones needs for native support (see section above).
Jars dont support "proper" code completion, a common developer trick is to stick
source code into the jar but that prevents usage with proprietary code. Cn1libs provide
full IDE code completion (with JavaDoc hints) without exposing the sources.
There are two use cases for wanting JARs and they both have very different solutions:
1. Modularity
2. Working with an existing JARs
Cn1libs address the modularity aspect allowing you to break that down. Existing jars
can sometimes be used native code settings but for the most part you would want to
adapt the code to abide by Codename One restrictions.

14.6.2.How To Use cn1libs?

20

Codename One has a large repository of 3rd party cn1libs , you can install a cn1lib by
placing it in the lib directory of your project then right clicking the project and selecting
Codename One Refresh cn1lib files.

20

https://www.codenameone.com/cn1libs.html

621

Advanced Topics/Under The Hood

Figure 14.17. Refresh cn1lib files menu option

Once refreshed the content of the cn1lib will be available to code completion and you
could just use it.
Notice that some cn1libs require additional configurations such as
build hints etc. so make sure to read the developers instructions
when integrating a 3rd party library.

Under the Hood of cn1lib Install

Refresh cn1lib files invokes the ant task refresh-libs . You could
automatically trigger a refresh as part of your build process by invoking that ant
task manually.
Technically that task invokes a custom task that unzips the content of the cn1lib
into a set of directories accessible to the build process. Classes and stub sources
are installed in lib/impl/cls & lib/impl/stubs respectively.
The native files are extracted to lib/impl/native . The classpath for the
main project and the ant build process know about these directories and include
them within their path.

622

Advanced Topics/Under The Hood

14.6.3.Creating a Simple cn1lib

Creating a cn1lib is trivial, we will get into more elaborate uses soon enough but for a
hello world cn1lib we can just use this 2 step process:

Figure 14.18. Select the CodenameOne Library Option

623

Advanced Topics/Under The Hood

Figure 14.19. Select the file name/destination. Notice that a Java 8

cn1lib requires Java 8 support in the parent project!
Once we go thru these steps we can define any source file within the library and it will
be accessible to the users of the library.

14.6.4.Build Hints in cn1libs

Some cn1libs are pretty simple to install, just place them under the lib directory and
refresh. However, many of the more elaborate cn1libs need some pretty complex
configurations. This is the case when native code is involved where we need to add
permissions or plist entries for the various native platforms to get everything to work.
This makes the cn1libs helpful but less than seamless which is where we want to go.
Codename
One
cn1libs
include
two
files
that
can
be
placed
into
the
root:
codenameone_library_required.properties
&
codenameone_library_appended.properties .
In
these
files
you
can
just
write
a
build
codename1.arg.ios.plistInject= for the various hints.

624

hint

as

Advanced Topics/Under The Hood

Notice the usage of the properties syntax for the build hint with the
codename1.arg prefix you would also need to escape reserved

characters for properties files.

The best way to discover the right syntax for such build hints is to set
them via the build hints GUI in a regular project and copy/paste them
from codenameone_settings.properties into the cn1lib file.
The obvious question is why do we need two files?
There are two types of build hints: required and appended.
Required build hints can be something like ios.objC=true which we want to
always work. E.g. if a cn1lib defines ios.objC=true and another cn1lib defines
ios.objC=false things wont work since one cn1lib wont get what it needs
In this case wed want the build to fail so we can remove the faulty cn1lib.
If two cn1libs define ios.objC=true there will be no collision as
the value would be identical
An
appended
property
would
be
ios.plistInject=<key>UIBackgroundModes</
key><array><string>audio</string> </array>

something

like

Notice that this can still collide e.g. if a different cn1lib defines its own background
mode. However, there are many valid cases where ios.plistInject can be used
for other things. In this case well append the content of the ios.plistInject into
the build hint if its not already there.
There are a couple of things you need to keep in mind:
Properties are merged with every "refresh libs" call not dynamically on the server.
This means it should be pretty simple for the developer to investigate issues in this
process.
Changing flags is problematic - there is no "uninstall" process. Since the data
is copied into the codenameone_settings.properties file. If you need to
change a flag later on you might need to alert users to make changes to their
properties essentially negating the value of this feature
So be very careful when adding properties here.
Its your responsibility as a library developer to decide which build hint goes into which
file!
625

Advanced Topics/Under The Hood

Codename One cant automate this process as the whole process of build hints is by
definition an ad hoc process.
The rule of thumb is that a build hint with a numeric or boolean value is always a
required property. If an entry has a string that you can append with another string then
its probably an appended entry.
These build hints are probably of the "required" type:
android.debug
android.release
android.installLocation
android.licenseKey
android.stack_size
android.statusbar_hidden

android.googleAdUnitId
android.includeGPlayServices
android.headphoneCallback
android.gpsPermission
android.asyncPaint
android.supportV4
android.theme
android.cusom_layout1
android.versionCode
android.captureRecord
android.removeBasePermissions
android.blockExternalStoragePermission
android.min_sdk_version
android.smallScreens
android.streamMode
android.enableProguard
android.targetSDKVersion
android.web_loading_hidden
facebook.appId
ios.keyboardOpen
ios.project_type
ios.newStorageLocation
ios.prerendered_icon
ios.application_exits
ios.themeMode
ios.xcode_version
javascript.inject_proxy
javascript.minifying
javascript.proxy.url
javascript.sourceFilesCopied

626

Advanced Topics/Under The Hood

javascript.teavm.version
rim.askPermissions
google.adUnitId
ios.includePush

ios.headphoneCallback
ios.enableAutoplayVideo
ios.googleAdUnitId
ios.googleAdUnitIdPadding
ios.enableBadgeClear
ios.locationUsageDescription
ios.bundleVersion
ios.objC
ios.testFlight
desktop.width
desktop.height
desktop.adaptToRetina
desktop.resizable
desktop.fontSizes
desktop.theme
desktop.themeMac
desktop.themeWin
desktop.windowsOutput
noExtraResources
j2me.iconSize

These build hints should probably be appended:

android.xapplication
android.xpermissions
android.xintent_filter
android.facebook_permissions
android.stringsXml
android.style

android.nonconsumable
android.xapplication_attr
android.xactivity
android.pushVibratePattern
android.proguardKeep
android.sharedUserId
android.sharedUserLabel
ios.urlScheme
ios.interface_orientation
ios.plistInject
ios.facebook_permissions
ios.applicationDidEnterBackground

627

Advanced Topics/Under The Hood

ios.viewDidLoad

ios.glAppDelegateHeader
ios.glAppDelegateBody
ios.beforeFinishLaunching
ios.afterFinishLaunching
ios.add_libs

cn1lib Structure/File Format

The cb1lib file format is quite simple, its a zip file containing zip files within it with
fixed names to support the various features.
The table below covers the files that can/should be a part of a cn1lib file:

Table 14.3. cn1lib structure

File Name

Required

Purpose

main.zip

Contains the bytecode and the library

binary data. This is effectively the
portable portion of the jar

stubs.zip

Stub source files (auto-generated)

containing javadocs to provide code
completion

manifest.properties

General properties of the library, this

isnt used for much at the moment

codenameone_ library_
appended.properties

Discussed above

codenameone_ library_
required.properties

Discussed above

nativeios.zip

Native iOS sources if applicable

nativeand.zip

Native Android sources if applicable

nativejavascript.zip

Native JavaScript sources if

applicable

nativerim.zip

Native RIM sources if applicable

nativese.zip

Native JavaSE sources if applicable

nativewin.zip

Native Windows sources if applicable

628

Advanced Topics/Under The Hood

File Name
nativeme.zip

Required

Purpose
Native Java ME sources if applicable

14.7.Integrating Android 3rd Party Libraries & JNI

While its pretty easy to use native interfaces to write Android native code some things
arent necessarily as obvious. E.g. if you want to integrate a 3rd party library, specifically
one that includes native C JNI code this process isnt as straightforward.
If you need to integrate such a library into your native calls you have the following 3
options:
1. The first option (and the easiest one) is to just place a Jar file in the native/android
directory. This will link your binary with the jar file. Just place the jar under the native/
android and the build server will pick it up and will add it to the classpath.
Notice that Android release apps are obfuscated by default which might cause
issues with such libraries if they reference APIs that are unavailable on Android.
You can workaround this by adding a build hint to the proguard obfuscation code
that blocs the obfuscation of the problematic classes using the build hint:
android.proguardKeep=-keep class com.mypackage.ProblemClass
{ *; }`
2. The second option is to add an Android Library Project. Not all 3rd party tools can
be packaged as a simple jar, some 3rd party tools need to declare activities add
permissions, resources, assets, and/or even add native code (.so files).
To link a Library project to your Codename One project open the Library project in
Eclipse or Android Studio and make sure the project builds, after the project was
built successfully remove the bin directory from the project and zip the whole project.
Rename the extension from .zip to .andlib and place the andlib file under
the native/android directory. The build server will pick it up and will link it to
the project.
3. The 3rd option is an aar files. The aar file is a binary format Google introduced
to represent an Android Library project (similarly to the cn1lib format). One of the
problem with the Android Library projects was the fact that it required the project
sources which made it difficult for 3rd party vendors to publish libraries.
As a result so android introduced the aar file which is a binary format that represents
21
a Library project. To learn more about arr you can read this .
21

http://tools.android.com/tech-docs/new-build-system/aar-format

629

Advanced Topics/Under The Hood

You can link an aar file by placing it under the native/android and the build server
will link it to the project.

14.8.Drag & Drop

Unlike other platforms that tried to create overly generic catch all APIs Codename One
tried to make things as simple as possible.
In Codename One only components can be dragged and drop targets are always
components. The logic of actually performing the operation indicated by the drop is the
responsibility of the person implementing the drop.
Some platforms e.g. AWT allow dragging abstract concepts such as
mime type elements. This allows dragging things like a text file into
the app, but that use case isnt realistic in mobile
The code below allows you to rearrange the items based on a sensible order. Notice
it relies on the default Container drop behavior.
Form hi = new Form("Rearrangeable Items", new BorderLayout());

String[] buttons = {"A Game of Thrones", "A Clash Of Kings", "A Storm Of
Swords",
"A Feast For Crows", "A Dance With Dragons", "The Winds of Winter", "A
Dream of Spring" };
Container box = new Container(BoxLayout.y());

box.setScrollableY(true);
box.setDropTarget(true);
java.util.List<String> got = Arrays.asList(buttons);
Collections.shuffle(got);
for(String current : got) {

MultiButton mb = new MultiButton(current);

box.add(mb);
mb.setDraggable(true);

hi.add(BorderLayout.NORTH, "Arrange The Titles").add(BorderLayout.CENTER,

box);
hi.show();

630

Advanced Topics/Under The Hood

Figure 14.20. Drag and drop demo

To enable dragging a component it must be flagged as draggable using
setDraggable(true) , to allow dropping the component onto another component
you must first enable the drop target with setDropTarget(true) and override some
methods (more on that later).
When dragging on top of a child component of a drop target the code recursively
searches for a drop target parent. Dropping a component on the child will automatically
find the right drop target, hence there is no need to make "everything" into a drop target.
You can override these methods in the draggable components:
631

Advanced Topics/Under The Hood

getDragImage - this generates an image preview of the component that will
be dragged. This automatically generates a sensible default so you dont need to
override it.
drawDraggedImage - this method will be invoked to draw the dragged image at
a given location, it might be useful to override it if you want to display some drag
related information such an additional icon based on location etc. (e.g. a move/copy
icon).
In the drop target you can override the following methods:
draggingOver - returns true if a drop operation at this point is permitted.
Otherwise releasing the component will have no effect.
dragEnter/Exit - useful to track and cleanup state related to dragging over a
specific component.
drop - the logic for dropping/moving the component must be implemented here!

14.9.Continuous Integration & Release Engineering

Codename One was essentially built for continuous integration since the build servers
are effectively a building block for such an architecture. However, there are several
problems with that: the first of which is limited server capacity.
If all users would start sending builds with every commit the servers would instantly
become unusable due to the heavy load. To circumvent this CI support is limited only
on the Enterprise level which allows Codename One to stock more servers and cope
with the rise in demand related to the feature.
To integrate with any CI solution just use the standard Ant targets such as buildfor-android-device , build-for-iphone-device etc.
Normally, this would be a problem since the build is sent but since it isnt blocking
you wouldnt get the build result and wouldnt be able to determine if the build
passed or failed. To enable this just edit the build XML and add the attribute
automated="true" to the codeNameOne tag in the appropriate targets.
This will deliver a result.zip file under the dist folder containing the binaries of
a successful build. It will also block until the build is completed. This should be pretty
easy to integrate with any CI system together with our automated testing solutions .
E.g. we can do a synchronous build like this:
632

Advanced Topics/Under The Hood

<target name="build-for-javascript-sync" depends="clean,copy-javascriptoverride,copy-libs,jar,clean-override">

<codeNameOne
jarFile="${dist.jar}"
displayName="${codename1.displayName}"
packageName = "${codename1.packageName}"
mainClassName = "${codename1.mainName}"
version="${codename1.version}"
icon="${codename1.icon}"
vendor="${codename1.vendor}"
subtitle="${codename1.secondaryTitle}"
automated="true"
targetType="javascript"
/>
</target>

This allows us to build a JavaScript version of the app automatically as part of a release
build script.

14.10.Android Lollipop ActionBar Customization

When running on Android Lollipop (5.0 or newer) the native action bar will use the
22
23
Lollipop design. This isnt applicable if you use the Toolbar or SideMenuBar this
wont be used.
To customize the colors of the native ActionBar on Lollipop define a colors.xml
file in the native/android directory of your project. It should look like this:
<resources>
<color name="colorPrimary">#ff00ff00</color>

<color name="colorPrimaryDark">#80ff0000</color>
<color name="colorAccent">#800000ff</color>
</resources>

14.11.Intercepting URLs On iOS & Android

A common trick in mobile application development, is communication between two
unrelated applications.
22
23

https://www.codenameone.com/javadoc/com/codename1/ui/Toolbar.html
https://www.codenameone.com/javadoc/com/codename1/ui/SideMenuBar.html

633

Advanced Topics/Under The Hood

In Android we can use intents which are pretty elaborate and can be used via
Display.execute , however what if you would like to expose the functionality of

your application to a different application running on the device. This would allow that
application to launch your application.
This isnt something we builtin to Codename One, however it does expose enough of
the platform capabilities to enable that functionality rather easily on Android.
On Android we need to define an intent filter which we can do using the
android.xintent_filter build hint, this accepts the XML to filter whether a
request is relevant to our application:
android.xintent_filter=<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />

<category android:name="android.intent.category.BROWSABLE" />

<data android:scheme="myapp" /> </intent-filter>

You can read more about it in this stack overflow question

24

To bind the myapp:// URL to your application. As a result typing myapp://x into
the Android browser will launch the application.

14.11.1.Passing Launch Arguments To The App

You can access the value of the URL that launched the app using:
String arg = Display.getInstance().getProperty("AppArg");

This value would be null if the app was launched via the icon.
iOS is practically identical to Android with some small caveats, iOSs equivalent of the
manifest is the plist.
You can inject more data into the plist by using the ios.plistInject build hint.
So the equivalent in the iOS side would be
ios.plistInject=<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLName</key>
24

http://stackoverflow.com/questions/11421048/android-ios-custom-uri-protocol-handling

634

Advanced Topics/Under The Hood

<string>com.yourcompany.myapp</string>

<key>CFBundleURLSchemes</key>
<string>myapp</string>
</array>

</dict>

<array>
</dict>

<dict>
</array>

However, that can conflict with the Facebook integration if you use
FacebookConnect which needs access to the schemes. To workaround it you can
use the build hint ios.urlScheme e.g.:
ios.urlScheme=<string>myapp</string>

14.12.Native Peer Components

Many Codename One developers dont truly grasp the reason for the separation
between peer (native) components and Codename One components. This is a crucial
thing you need to understand especially if you plan on working with native widgets e.g.
Web Browser, native maps, text input, media and native interfaces (which can return
a PeerComponent ).
Codename One draws all of its widgets on its own, this is a concept which was modeled
in part after Swing. This allows functionality that cant be achieved in native widget
platforms:
1. The Codename One GUI builder & simulator are almost identical to the device notice that this also enables the build cloud, otherwise device specific bugs would
overwhelm development and make the build cloud redundant.
2. Ability to override everything - paint, pointer, key events are all overridable and
replaceable. Developers can also paint over everything e.g. glasspane and layered
pane.
3. Consistency - provides identical functionality on all platforms for the most part.
This all contributes to our ease of working with Codename One and maintaining
Codename One. More than 95% of Codename Ones code is in Java hence its really
portable and pretty easy to maintain!

14.12.1.Why does Codename One Need Native Widgets at

all?
We need the native device to do input, html rendering etc. these are just too big and
too complex tasks for Codename One to do from scratch.
635

Advanced Topics/Under The Hood

They are sometimes impossible to perform without the native platform. E.g. the virtual
keyboard input on the devices is tied directly to the native text input. Its impractical to
implement everything from scratch for all languages, dictionaries etc. The result would
be sub-par.
A web browser cant be implemented in this day and age without a JavaScript JIT and
including a JIT within an iOS app is prohibited by Apple.

14.12.2.So whats the problems with native widgets?

Codename One does pretty much everything on the EDT (Event Dispatch Thread), this
provides a lot of cool features e.g. modal dialogs, invokeAndBlock etc.
However native widgets have to be drawn on the devices native UI thread.
This means that drawing looks something like this:
1. Loop over all Codename One components and paint them.
2. Loop over all native peer components and paint them.
This effectively means that all peer components are drawn on top of the Codename
One components.
This was also the case in AWT/Swing to one degree or another

14.12.3.So how do we show dialogs on top of Peer

Components?
Codename One grabs a screenshot of the peer, hide it and then we can just show
the screenshot. Since the screenshot is static it can be rendered via the standard UI.
Naturally we cant do that always since grabbing a screenshot is an expensive process
on all platforms and must be performed on the native device thread.

14.12.4.Why cant we combine peer component scrolling and

Codename One scrolling?
Since the form title/footer etc. are drawn by Codename One the peer component
might paint itself on top of them. Clipping a peer component is often pretty difficult.
636

Advanced Topics/Under The Hood

Furthermore, if the user drags his finger within the peer component he might trigger the
native scroll within the might collide with our scrolling?

14.12.5.Native Components In The First Form

There is also another problem that might be counter intuitive. iOS has screenshot
images representing the first form. If your first page is an HTML or a native map (or
other peer widget) the screenshot process on the build server will show fallback code
instead of the real thing thus providing sub-par behavior.
Its impractical to support something like HTML for the screenshot process since it would
also look completely different from the web component running on the device.
You can read more about the screenshot process here.

14.13.Integrating 3rd Party Native SDKs

The following is a description of the procedure that was used to create the Codename
25
One FreshDesk library . This process can be easily adapted to wrap any native SDK
on Android and iOS.

14.13.1.Step 1 : Review the FreshDesk SDKs

Before we begin, well need to review the Android and iOS SDKs.
1. FreshDesk Android SDK: Integration Guide
2. FreshDesk iOS SDK: Integration Guide

28

26

| API Docs

| API Docs

27

29

In reviewing the SDKs, we are looking for answers to two questions:

1. What should my Codename One FreshDesk API look like?
2. What will be involved in integrating the native SDK in my app or lib?
25
http://shannah.github.io/cn1-freshdesk/
26
http://developer.freshdesk.com/mobihelp/android/integration_guide/
27
http://developer.freshdesk.com/mobihelp/android/api/reference/com/freshdesk/mobihelp/packagesummary.html
28
http://developer.freshdesk.com/mobihelp/ios/integration_guide/
29
http://developer.freshdesk.com/mobihelp/ios/api/

637

Advanced Topics/Under The Hood

14.13.2.Step 2: Designing the Codename One Public API

When designing the Codename One API, we should begin by looking at the Javadocs

30

for the native Android SDK. If the class hierarchy doesnt look too elaborate, we may
decide to model our Codename One public API fairly closely on the Android API. On
the other hand, if we only need a small part of the SDKs functionality, we may choose
to create my abstractions around just the functionality that we need.
In the case of the FreshDesk SDK, it looks like most of the functionality is handled by
one central class Mobihelp , with a few other POJO classes for passing data to and
from the service. This is a good candidate for a comprehensive Codename One API.
Before proceeding, we also need to look at the iOS API to see if there are any features
that arent included. While naming conventions in the iOS API are a little different than
those in the Android API, it looks like they are functionally the same.
Therefore, I choose to create a class hierarchy and API that closely mirrors the Android
SDK.

14.13.3.Step 3: The Architecture and Internal APIs

A Codename One library that wraps a native SDK, will generally consist of the following:
1. Public Java API, consisting of pure Java classes that are intended to be used by
the outside world.
2. Native Interface(s). The Native Interface(s) act as a conduit for the public Java
API to communicate to the native SDK. Parameters in native interface methods are
limited to primitive types, arrays of primitive types, and Strings, as are return values.
3. Native code. Each platform must include an implementation of the Native
Interface(s). These implementations are written in the native language of the
platform (e.g. Java for Android, and Objective-C for iOS).
4. Native dependencies. Any 3rd party libraries required for the native code to work,
need to be included for each platform. On android, this may mean bundling .jar
files, .aar files, or .andlib files. On iOS, this may mean bundling .h files, .a files,
and .bundle files.
5. Build hints. Some libraries will require you to add some extra build hints to your
project. E.g. On Android you may need to add permissions to the manifest, or
30

http://developer.freshdesk.com/mobihelp/android/api/reference/com/freshdesk/mobihelp/package-

summary.html

638

Advanced Topics/Under The Hood

define services in the <Application> section of the manifest. On iOS, this may
mean specifying additional core frameworks for inclusion, or adding build flags for
compilation.
The following diagram shows the dependencies in a native library:

Figure 14.21. Relationship between native & Codename One API

UML Diagram
In the specific case of our FreshDesk API, the public API and classes will look like:
639

Advanced Topics/Under The Hood

31

https://github.com/shannah/cn1-freshdesk/blob/master/cn1-freshdesk-demo/src/com/codename1/
freshdesk/Mobihelp.java
32
https://github.com/shannah/cn1-freshdesk/blob/master/cn1-freshdesk-demo/src/com/codename1/
freshdesk/FeedbackRequest.java
Figure 14.22. Freshdesk API Integration
33
https://github.com/shannah/cn1-freshdesk/blob/master/cn1-freshdesk-demo/src/com/codename1/
freshdesk/FeedbackType.java
34
https://github.com/shannah/cn1-freshdesk/blob/master/cn1-freshdesk-demo/src/com/codename1/
freshdesk/MobihelpConfig.java

640

Advanced Topics/Under The Hood

Things to Notice
31

1. The public API consists of the main class ( Mobihelp ), and a few supporting
32
33
34
classes ( FeedbackRequest , FeedbackType , MobihelpConfig ,
35
MobihelpCallbackStatus ), which were copied almost directly from the
Android SDK.
2. The only way for the public API to communicate with the native SDK is via the
36
MobihelpNative
interface.
37

3. We introduced the MobihelpNativeCallback class to facilitate native code

calling back into the public API. This was necessary for a few methods that used
asynchronous callbacks.

14.13.4.Step 4: Implement the Public API and Native

Interface
We have already looked at the final product of the public API in the previous step, but
lets back up and walk through the process step-by-step.
I wanted to model my API closely around the Android API, and the central class that
includes all of the functionality of the SDK is the com.freshdesk.mobihelp.Mobihelp
38
class , so we begin there.
Well start by creating our own package ( com.codename1.freshdesk ) and our own
Mobihelp class inside it.

Adapting Method Signatures

The Context parameter
39

In a first glance at the com.freshdesk.mobihelp.Mobihelp API we see that many of

40
the methods take a parameter of type android.content.Context . This class
35

https://github.com/shannah/cn1-freshdesk/blob/master/cn1-freshdesk-demo/src/com/codename1/
freshdesk/MobihelpCallbackStatus.java
36
https://github.com/shannah/cn1-freshdesk/blob/master/cn1-freshdesk-demo/src/com/codename1/
freshdesk/MobihelpNative.java
37
https://github.com/shannah/cn1-freshdesk/blob/master/cn1-freshdesk-demo/src/com/codename1/
freshdesk/MobihelpNativeCallback.java
38
http://developer.freshdesk.com/mobihelp/android/api/reference/com/freshdesk/mobihelp/Mobihelp.html
39
http://developer.freshdesk.com/mobihelp/android/api/reference/com/freshdesk/mobihelp/Mobihelp.html

641

Advanced Topics/Under The Hood

is part of the core Android SDK, and will not be accessible to any pure Codename One
APIs. Therefore, our public API cannot include any such references. Luckily, well be
able to access a suitable context in the native layer, so well just omit this parameter
from our public API, and inject them in our native implementation.
Hence, the method signature public static final void setUserFullName
(Context context, String name) will simply become public static final
void setUserFullName (String name) in our public API.

Non-Primitive Parameters
Although our public API isnt constrained by the same rules as our Native Interfaces
with respect to parameter and return types, we need to be cognizant of the fact that
parameters we pass to our public API will ultimately be funnelled through our native
interface. Therefore, we should pay attention to any parameters or return types that
cant be passed directly to a native interface, and start forming a strategy for them. E.g.
consider the following method signature from the Android Mobihelp class:
public static final void showSolutions (Context activityContext,
ArrayList<String> tags)

Weve already decided to just omit the Context parameter in our API, so thats a
non-issue. But what about the ArrayList<String> tags parameter? Passing this
to our public API is no problem, but when we implement the public API, how will we
pass this ArrayList to our native interface, since native interfaces dont allow us to
arrays of strings as parameters?
I generally use one of three strategies in such cases:
1. Encode the parameter as either a single String (e.g. using JSON or some other
easily parseable format) or a byte[] array (in some known format that can easily be
parsed in native code).
2. Store the parameter on the Codename One side and pass some ID or token that
can be used on the native side to retrieve the value.
3. If the data structure can be expressed as a finite number of primitive values,
then simply design the native interface method to take the individual values
41
as parameters instead of a single object. E.g. If there is a User
class with
40
41

http://developer.android.com/reference/android/content/Context.html
https://www.codenameone.com/javadoc/com/codename1/facebook/User.html

642

Advanced Topics/Under The Hood

properties name and phoneNumber , the native interface can just have name
and phoneNumber parameters rather than a single `user parameter.
In this case, because an array of strings is such a simple data structure, I decided to use
a variation on strategy number 1: Merge the array into a single string with a delimiter.
In any case, we dont have to come up with the specifics right now, as we are still on
the public API, but it will pay dividends later if we think this through ahead of time.

Callbacks
It is quite often the case that native code needs to call back into Codename One code
when an event occurs. This may be connected directly to an API method call (e.g.
as the result of an asynchronous method invocation), or due to something initiated by
the operating system or the native SDK on its own (e.g. a push notification, a location
event, etc..).
Native code will have access to both the Codename One API and any native APIs in
your app, but on some platforms, accessing the Codename One API may be a little
tricky. E.g. on iOS youll be calling from Objective-C back into Java which requires
knowledge of Codename Ones java-to-objective C conversion process. In general, I
have found that the easiest way to facilitate callbacks is to provide abstractions that
involve static java methods (in Codename One space) that accept and return primitive
types.
In the case of our Mobihelp class, the following method hints at the need to have
a "callback plan":
public static final void getUnreadCountAsync (Context context,
UnreadUpdatesCallback callback)

The interface definition for UnreadUpdatesCallback is:

public interface UnreadUpdatesCallback {

//This method is called once the unread updates count is available.

void onResult(MobihelpCallbackStatus status, Integer count);

I.e. If we were to implement this method (which I plan to do), we need to have a way for
the native code to call the callback.onResult() method of the passed parameter.
643

Advanced Topics/Under The Hood

So we have two issues that will need to be solved here:
1. How to pass the callback object through the native interface.
2. How to call the callback.onResult() method from native code at the right
time.
For the first issue, well use strategy #2 that we mentioned previously: (Store the
parameter on the Codename One side and pass some ID or token that can be used
on the native side to retrieve the value).
For the second issue, well create a static method that can take the token generated to
solve the first issue, and call the stored callback objects onResult() method. We
42
abstract both sides of this process using the MobihelpNativeCallback class .
public class MobihelpNativeCallback {
private static int nextId = 0;

private static Map<Integer,UnreadUpdatesCallback> callbacks = new

HashMap<Integer,UnreadUpdatesCallback>();

static int registerUnreadUpdatesCallback(UnreadUpdatesCallback

callback) {
callbacks.put(nextId, callback);
}

return nextId++;

public static void fireUnreadUpdatesCallback(int callbackId, final int

status, final int count) {

final UnreadUpdatesCallback cb = callbacks.get(callbackId);

if (cb != null) {

callbacks.remove(callbackId);

Display.getInstance().callSerially(new Runnable() {
public void run() {

MobihelpCallbackStatus status2 =
MobihelpCallbackStatus.values()[status];
cb.onResult(status2, count);
}

}
42

});

https://github.com/shannah/cn1-freshdesk/blob/master/cn1-freshdesk-demo/src/com/codename1/

freshdesk/MobihelpNativeCallback.java

644

Advanced Topics/Under The Hood

Things to notice here:

1. This class uses a static Map<Integer,UnreadUpdatesCallback> member to
keep track of all callbacks, mapping a unique integer ID to each callback.
2. The
registerUnreadUpdatesCallback()
method
takes
an
UnreadUpdatesCallback object, places it in the callbacks map, and returns
the integer token that can be used to fire the callback later. This method would
be called by the public API inside the getUnreadCountAsync() method
implementation to convert the callback into an integer, which can then be
passed to the native API.
3. The fireUnreadUpdatesCallback() method would be called later from native
code. Its first parameter is the token for the callback to call.

4. We wrap the onResult() call inside a Display.callSerially() invocation

to ensure that the callback is called on the EDT. This is a general convention that
is used throughout Codename One, and youd be well-advised to follow it. Event
handlers should be run on the EDT unless there is a good reason not to - and in
that case your documentation and naming conventions should make this clear to
avoid accidentally stepping into multithreading hell!

Initialization
Most Native SDKs include some sort of initialization method where you pass your
developer and application credentials to the API. When I filled in FreshDesks webbased form to create a new application, it generated an application ID, an app "secret",
and a "domain". The SDK requires me to pass all three of these values to its init()
method via the MobihelpConfig class.
Note, however, that FreshDesk (and most other service provides that have native
SDKs) requires me to create different Apps for each platform. This means that my App
ID and App secret will be different on iOS than they will be on Android.
Therefore our public API needs to enable us to provide multiple credentials in the same
app, and our API needs to know to use the correct credentials depending on the device
that the app is running on.
There are many solutions to this problem, but the one I chose was to provide two
different init() methods:
645

Advanced Topics/Under The Hood

public final static void initIOS(MobihelpConfig config)

and
public final static void initAndroid(MobihelpConfig config)

Then I can set up the API with code like:

MobihelpConfig config = new MobihelpConfig();

config.setAppSecret("xxxxxxx");
config.setAppId("freshdeskdemo-2-xxxxxx");
config.setDomain("codenameonetest1.freshdesk.com");
Mobihelp.initIOS(config);
config = new MobihelpConfig();

config.setAppSecret("yyyyyyyy");
config.setAppId("freshdeskdemo-1-yyyyyyyy");
config.setDomain("https://codenameonetest1.freshdesk.com");
Mobihelp.initAndroid(config);

The Resulting Public API

public class Mobihelp {
private static char[] separators = new char[]

{',','|','/','@','#','%','!','^','&','*','=','+','*','<'};
private static MobihelpNative peer;

public static boolean isSupported() {

}

....

public static void setPeer(MobihelpNative peer) {

}

....

//Attach the given custom data (key-value pair) to the conversations/

tickets.

public final static void addCustomData(String key, String value) {

}

...

646

Advanced Topics/Under The Hood

//Attach the given custom data (key-value pair) to the conversations/

tickets with the ability to flag sensitive data.

public final static void addCustomData(String key, String

value, boolean isSensitive) {

}

...

//Clear all breadcrumb data.

public final static void clearBreadCrumbs() {

}

...

//Clear all custom data.

public final static void clearCustomData() {

}

...

//Clears User information.

public final static void clearUserData() {

...

//Retrieve the number of unread items across all the conversations for

the user synchronously i.e.

public final static int getUnreadCount() {

...

//Retrieve the number of unread items across all the conversations

for the user asynchronously, count is delivered to the supplied

UnreadUpdatesCallback instance Note : This may return 0 or stale value

when there is no network connectivity etc

public final static void getUnreadCountAsync(UnreadUpdatesCallback

callback) {
...
}

//Initialize the Mobihelp support section with necessary app

configuration.

public final static void initAndroid(MobihelpConfig config) {

}

...

public final static void initIOS(MobihelpConfig config) {

}

...

//Attaches the given text as a breadcrumb to the conversations/

tickets.

647

Advanced Topics/Under The Hood

public final static void leaveBreadCrumb(String crumbText) {
}

...

//Set the email of the user to be reported on the Freshdesk Portal

public final static void setUserEmail(String email) {
}

...

//Set the name of the user to be reported on the Freshdesk Portal.

public final static void setUserFullName(String name) {
}

...

//Display the App Rating dialog with option to Rate, Leave feedback

etc

public static void showAppRateDialog() {

}

...

//Directly launch Conversation list screen from anywhere within the

application

public final static void showConversations() {

}

...

//Directly launch Feedback Screen from anywhere within the

application.
{

public final static void showFeedback(FeedbackRequest feedbackRequest)

...

//Directly launch Feedback Screen from anywhere within the

application.

public final static void showFeedback() {

}

...

//Displays the Support landing page (Solution Article List Activity)

where only solutions tagged with the given tags are displayed.

public final static void showSolutions(ArrayList<String> tags) {

}

...

private static String findUnusedSeparator(ArrayList<String> tags) {

...

648

Advanced Topics/Under The Hood

//Displays the Support landing page (Solution Article List Activity)

from where users can do the following

//View solutions,

//Search solutions,

public final static void showSolutions() {

}

...

//Displays the Integrated Support landing page where only solutions

tagged with the given tags are displayed.

public final static void showSupport(ArrayList<String> tags) {

}

...

//Displays the Integrated Support landing page (Solution Article List

Activity) from where users can do the following

//View solutions,

//Search solutions,
//

Start a new conversation,

//View existing conversations update/ unread count etc

public final static void showSupport() {
}

...

The Native Interface

The final native interface is nearly identical to our public API, except in cases where
the public API included non-primitive parameters.
public interface MobihelpNative extends NativeInterface {
/**
* @return the appId
*/
public String config_getAppId();
/**
* @param appId the appId to set
*/
public void config_setAppId(String appId);
/**
* @return the appSecret

649

Advanced Topics/Under The Hood

*/
public String config_getAppSecret();
/**
* @param appSecret the appSecret to set
*/
public void config_setAppSecret(String appSecret);
/**
* @return the domain
*/

public String config_getDomain();

/**
* @param domain the domain to set
*/
public void config_setDomain(String domain) ;
/**
* @return the feedbackType
*/
public int config_getFeedbackType() ;
/**
* @param feedbackType the feedbackType to set
*/
public void config_setFeedbackType(int feedbackType);
/**
* @return the launchCountForReviewPrompt
*/
public int config_getLaunchCountForReviewPrompt() ;

/**
* @param launchCountForReviewPrompt the launchCountForReviewPrompt to
set
*/
public void config_setLaunchCountForReviewPrompt(int

launchCountForReviewPrompt);
/**
* @return the prefetchSolutions
*/

public boolean config_isPrefetchSolutions();

/**
* @param prefetchSolutions the prefetchOptions to set
*/
public void config_setPrefetchSolutions(boolean prefetchSolutions);
/**
* @return the autoReplyEnabled

650

Advanced Topics/Under The Hood

*/
public boolean config_isAutoReplyEnabled();
/**
* @param autoReplyEnabled the autoReplyEnabled to set
*/
public void config_setAutoReplyEnabled(boolean autoReplyEnabled) ;
/**
* @return the enhancedPrivacyModeEnabled
*/
public boolean config_isEnhancedPrivacyModeEnabled() ;
/**
* @param enhancedPrivacyModeEnabled the enhancedPrivacyModeEnabled to
set
*/
public void config_setEnhancedPrivacyModeEnabled(boolean

enhancedPrivacyModeEnabled) ;

//Attach the given custom data (key-value pair) to the conversations/

tickets.

public void addCustomData(String key, String value);

//Attach the given custom data (key-value pair) to the conversations/

tickets with the ability to flag sensitive data.

public void addCustomDataWithSensitivity(String key, String

value, boolean isSensitive);

//Clear all breadcrumb data.

public void clearBreadCrumbs() ;

//Clear all custom data.

public void clearCustomData();

//Clears User information.

public void clearUserData();

//Retrieve the number of unread items across all the conversations for

the user synchronously i.e.

public int getUnreadCount();

//Retrieve the number of unread items across all the conversations

for the user asynchronously, count is delivered to the supplied

UnreadUpdatesCallback instance Note : This may return 0 or stale value

when there is no network connectivity etc

public void getUnreadCountAsync(int callbackId);

651

Advanced Topics/Under The Hood

public void initNative();
//Attaches the given text as a breadcrumb to the conversations/

tickets.

public

void leaveBreadCrumb(String crumbText);

//Set the email of the user to be reported on the Freshdesk Portal

public void setUserEmail(String email);
//Set the name of the user to be reported on the Freshdesk Portal.
public void setUserFullName(String name);

//Display the App Rating dialog with option to Rate, Leave feedback

etc

public void showAppRateDialog();

//Directly launch Conversation list screen from anywhere within the

application

public void showConversations();

//Directly launch Feedback Screen from anywhere within the

application.

public void showFeedbackWithArgs(String subject, String description);

//Directly launch Feedback Screen from anywhere within the

application.

public void showFeedback();

//Displays the Support landing page (Solution Article List Activity)

where only solutions tagged with the given tags are displayed.

public void showSolutionsWithTags(String tags, String separator);

//Displays the Support landing page (Solution Article List Activity)

from where users can do the following

//View solutions,

//Search solutions,

public void showSolutions();

//Displays the Integrated Support landing page where only solutions

tagged with the given tags are displayed.

public void showSupportWithTags(String tags, String separator);

//Displays the Integrated Support landing page (Solution Article List

Activity) from where users can do the following

//View solutions,

//Search solutions,
//

Start a new conversation,

//View existing conversations update/ unread count etc

652

Advanced Topics/Under The Hood

public void showSupport();

Notice also, that the native interface includes a set of methods with names prefixed with
config__ . This is just a naming conventions I used to identify methods that map to
the MobihelpConfig class. I could have used a separate native interface for these,
but decided to keep all the native stuff in one class for simplicity and maintainability.

Connecting the Public API to the Native Interface

So we have a public API, and we have a native interface. The idea is that the public
API should be a thin wrapper around the native interface to smooth out rough edges
that are likely to exist due to the strict set of rules involved in native interfaces. Well,
therefore, use delegation inside the Mobihelp class to provide it a reference to an
instance of MobihelpNative :
public class Mobihelp {

private static MobihelpNative peer;

//...

Well initialize this peer inside the init() method of the Mobihelp class. Notice,
though that init() is private since we have provided abstractions for the Android
and iOS apps separately:
//Initialize the Mobihelp support section with necessary app

configuration.

public final static void initAndroid(MobihelpConfig config) {

if ("and".equals(Display.getInstance().getPlatformName())) {

init(config);

public final static void initIOS(MobihelpConfig config) {

if ("ios".equals(Display.getInstance().getPlatformName())) {

init(config);

private static void init(MobihelpConfig config) {

peer = (MobihelpNative)NativeLookup.create(MobihelpNative.class);
peer.config_setAppId(config.getAppId());

653

Advanced Topics/Under The Hood

peer.config_setAppSecret(config.getAppSecret());

peer.config_setAutoReplyEnabled(config.isAutoReplyEnabled());
peer.config_setDomain(config.getDomain());
peer.config_setEnhancedPrivacyModeEnabled(config.isEnhancedPrivacyModeEnabled());
if (config.getFeedbackType() != null) {

peer.config_setFeedbackType(config.getFeedbackType().ordinal());
}
peer.config_setLaunchCountForReviewPrompt(config.getLaunchCountForReviewPrompt());
peer.config_setPrefetchSolutions(config.isPrefetchSolutions());
peer.initNative();
}

Things to Notice:
1. The initAndroid() and initIOS() methods include a check to see if they
are running on the correct platform. Ultimately they both call init() .
2. The init() method, uses the NativeLookup
interface.

43

class to instantiate our native

Implementing the Glue Between Public API and Native Interface

For most of the methods in the Mobihelp class, we can see that the public API will
just be a thin wrapper around the native interface. E.g. the public API implementation
of setUserFullName(String) is:
public final static void setUserFullName(String name) {
}

peer.setUserFullName(name);

For some other methods, the public API needs to break apart the parameters into a
form that the native interface can accept. E.g. the init() method, shown above,
takes a MobihelpConfig object as a parameter, but it passed the properties of the
config object individually into the native interface.
Another example, is the showSupport(ArrayList<String> tags) method.
The corresponding native interface method that is wraps is showSupport(String
43

https://www.codenameone.com/javadoc/com/codename1/system/NativeLookup.html

654

Advanced Topics/Under The Hood

tags, `String separator)` - i.e it needs to merge all tags into a single delimited
string, and pass then to the native interface along with the delimiter used. The
implementation is:
public final static void showSupport(ArrayList<String> tags) {
String separator = findUnusedSeparator(tags);
StringBuilder sb = new StringBuilder();
for (String tag : tags) {

sb.append(tag).append(separator);

}
peer.showSupportWithTags(sb.toString().substring(0, sb.length()separator.length()), separator);
}

The only other non-trivial wrapper is the getUnreadCountAsync() method that we

discussed before:
public final static void getUnreadCountAsync(UnreadUpdatesCallback

callback) {

int callbackId =

MobihelpNativeCallback.registerUnreadUpdatesCallback(callback);
peer.getUnreadCountAsync(callbackId);
}

14.13.5.Step 5: Implementing the Native Interface in

Android
Now that we have set up our public API and our native interface, it is time to work on the
native side of things. You can generate stubs for all platforms in your IDE (Netbeans
in my case), by right clicking on the MobihelpNative class in the project explorer
and selecting "Generate Native Access".

655

Advanced Topics/Under The Hood

Figure 14.23. Generate Native Access Menu Item

This will generate a separate directory for each platform inside your projects native
directory:

Figure 14.24. Native generated sources directory view

656

Advanced Topics/Under The Hood

Inside the android directory, this generates a com/codename1/freshdesk/
MobihelpNativeImpl class with stubs for each method.
Our implementation will be a thin wrapper around the native Android SDK. See the
source here

44

Some highlights:
1. Context : The native API requires us to pass a context object as a parameter on
many methods. This should be the context for the current activity. It will allow the
FreshDesk API to know where to return to after it has done its thing. Codename One
provides a class called AndroidNativeUtil that allows us to retrieve the apps
Activity (which includes the Context). Well wrap this with a convenience method
in our class as follows:
private static Context context() {
return

com.codename1.impl.android.AndroidNativeUtil.getActivity().getApplicationContext();

This will enable us to easily wrap the freshdesk native API. E.g.:
public void clearUserData() {
}

com.freshdesk.mobihelp.Mobihelp.clearUserData(context());

2. runOnUiThread() - Many of the calls to the FreshDesk API may have been
made from the Codename One EDT. However, Android has its own event
dispatch thread that should be used for interacting with native Android UI.
Therefore, any API calls that look like they initiate some sort of native Android UI
process should be wrapped inside Androids runOnUiThread() method which
is similar to Codename Ones Display.callSerially() method. E.g. see the
showSolutions() method:
public void showSolutions() {

activity().runOnUiThread(new Runnable() {
public void run() {

44

https://github.com/shannah/cn1-freshdesk/blob/master/cn1-freshdesk-demo/native/android/com/

codename1/freshdesk/MobihelpNativeImpl.java

657

Advanced Topics/Under The Hood

com.freshdesk.mobihelp.Mobihelp.showSolutions(context());
}
});
}

(Note here that the activity() method is another convenience method to

retrieve the apps current Activity from the AndroidNativeUtil class).
3. Callbacks. We discussed, in detail, the mechanisms we put in place to enable our
native code to perform callbacks into Codename One. You can see the native side
of this by viewing the getUnreadCountAsync() method implementation:
public void getUnreadCountAsync(final int callbackId) {
activity().runOnUiThread(new Runnable() {
public void run() {

com.freshdesk.mobihelp.Mobihelp.getUnreadCountAsync(context(), new
com.freshdesk.mobihelp.UnreadUpdatesCallback() {
public void

onResult(com.freshdesk.mobihelp.MobihelpCallbackStatus status, Integer

count) {
MobihelpNativeCallback.fireUnreadUpdatesCallback(callbackId,
status.ordinal(), count);
}
});
}
});
}

14.13.6.Step 6: Bundling the Native SDKs

The last step (at least on the Android side) is to bundle the FreshDesk SDK. For
Android, there are a few different scenarios youll run into for embedding SDKs:
1. The SDK includes only Java classes - NO XML UI files, assets, or resources that
arent included inside a simple .jar file. In this case, you can just place the .jar file
inside your projects native/android directory.
2. The SDK includes some XML UI files, resources, and assets. In this case, the
SDK is generally distributed as an Android project folder that can be imported into
658

Advanced Topics/Under The Hood

an Eclipse or Android studio workspace. In general, in this case, you would need to
zip the entire directory and change the extension of the resulting .zip file to ".andlib",
and place this in your projects native/android directory.
3. The SDK is distributed as an .aar file- In this case you can just copy the .aar
file into your native/android directory.

The FreshDesk SDK

The FreshDesk (aka Mobihelp) SDK is distributed as a project folder (i.e.
scenario 2 from the above list). Therefore, our procedure is to download the
45
SDK (download link ), and rename it from mobihelp_sdk_android.zip to
mobihelp_sdk_android.andlib , and copy it into our native/android
directory.

Dependencies
Unfortunately, in this case theres a catch. The Mobihelp SDK includes a dependency:
Mobihelp SDK depends on AppCompat-v7 (Revision 19.0+) Library. You
will need to update project.properties to point to the Appcompat library.
If we look inside the project.properties file (inside the Mobihelp SDK directory--i.e. youd need to extract it from the zip to view its contents), youll see the dependency
listed:
android.library.reference.1=../appcompat_v7

I.e. it is expecting to find the appcompat_v7 library located in the same parent
directory as the Mobihelp SDK project. After a little bit of research (if youre not yet
familiar with the Android AppCompat support library), we find that the AppCompat_v7
library is part of the Android Support library, which can can installed into your local
46
Android SDK using Android SDK Manager. Installation processed specified here .
After installing the support library, you need to retrieve it from your Android SDK.
You can find that .aar file inside the ANDROID_HOME/sdk/extras/android/
m2repository/com/android/support/appcompat-v7/19.1.0/ directory (for
version 19.1.0). The contents of that directory on my system are:
45
46

https://s3.amazonaws.com/assets.mobihelp.freshpo.com/sdk/mobihelp_sdk_android.zip
https://developer.android.com/tools/support-library/setup.html

659

Advanced Topics/Under The Hood

appcompat-v7-19.1.0.aar appcompat-v7-19.1.0.pom
appcompat-v7-19.1.0.aar.md5 appcompat-v7-19.1.0.pom.md5
appcompat-v7-19.1.0.aar.sha1 appcompat-v7-19.1.0.pom.sha1

There are two files of interest here:

1. appcompat-v7-19.1.0.aar - This is the actual library that we need to include in our
project to satisfy the Mobisdk dependency.
2. appcompat-v7-19.1.0.pom - This is the Maven XML file for the library. It will show
us any dependencies that the appcompat library has. We will also need to include
these dependencies:
<dependencies>
<dependency>
<groupId>com.android.support</groupId>
<artifactId>support-v4</artifactId>
<version>19.1.0</version>
<scope>compile</scope>
</dependency>
</dependencies>

i.e. We need to include the support-v4 library version 19.1.0 in our project.
This is also part of the Android Support library. If we back up a couple of
directories to: ANDROID_HOME/sdk/extras/android/m2repository/com/
android/support , well see it listed there:
appcompat-v7
palette-v7
cardview-v7
recyclerview-v7
gridlayout-v7
support-annotations
leanback-v17
support-v13
mediarouter-v7
support-v4
multidex
test
multidex-instrumentation

+ And if we look inside the appropriate version directory of support-v4

(in ANDROID_HOME/sdk/extras/android/m2repository/com/android/
support/support-v4/19.1.0 ), we see:
support-v4-19.1.0-javadoc.jar support-v4-19.1.0.jar
support-v4-19.1.0-javadoc.jar.md5 support-v4-19.1.0.jar.md5

660

Advanced Topics/Under The Hood

support-v4-19.1.0-javadoc.jar.sha1 support-v4-19.1.0.jar.sha1
support-v4-19.1.0-sources.jar support-v4-19.1.0.pom
support-v4-19.1.0-sources.jar.md5 support-v4-19.1.0.pom.md5
support-v4-19.1.0-sources.jar.sha1 support-v4-19.1.0.pom.sha1

Looks like this library is pure Java classes, so we only need to include the
support-v4-19.1.0.jar file into our project. Checking the .pom file we see
that there are no additional dependencies we need to add.
So, to summarize our findings, we need to include the following files in our native/
android directory:
1. appcompat-v7-19.1.0.aar
2. support-v4-19.1.0.jar
And since our Mobihelp SDK lists the appcompat_v7 dependency path as "../
appcompat_v7" in its project.properties file, we are going to rename appcompatv7-19.1.0.aar to appcompat_v7.aar .
When all is said and done, our native/android directory should contain the
following:
appcompat_v7.aar mobihelp.andlib
com
support-v4-19.1.0.jar

14.13.7.Step 7 : Injecting Android Manifest and Proguard

Config
The final step on the Android side is to inject necessary permissions and services into
the projects AndroidManifest.xml file.
We can find the manifest file injections required by opening the
AndroidManifest.xml file from the MobiHelp SDK project. Its contents are as
follows:
<?xml version="1.0" encoding="utf-8"?>

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.freshdesk.mobihelp"
android:versionCode="1"
android:versionName="1.0" >
<uses-sdk

661

Advanced Topics/Under The Hood

android:minSdkVersion="10" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_LOGS" />

<usespermission android:name="android.permission.ACCESS_NETWORK_STATE" />

<usespermission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<application>
<activity
android:name="com.freshdesk.mobihelp.activity.SolutionArticleListActivity"
android:configChanges="orientation|screenSize"
android:theme="@style/Theme.Mobihelp"
android:windowSoftInputMode="adjustPan" >
</activity>
<activity

android:name="com.freshdesk.mobihelp.activity.FeedbackActivity"
android:configChanges="keyboardHidden|orientation|screenSize"
android:theme="@style/Theme.Mobihelp"
android:windowSoftInputMode="adjustResize|stateVisible" >
</activity>
<activity
android:name="com.freshdesk.mobihelp.activity.InterstitialActivity"
android:configChanges="orientation|screenSize"
android:theme="@style/Theme.AppCompat">
</activity>
<activity
android:name="com.freshdesk.mobihelp.activity.TicketListActivity"

android:parentActivityName="com.freshdesk.mobihelp.activity.SolutionArticleListActivit
android:theme="@style/Theme.Mobihelp" >
<!-- Parent activity meta-data to support 4.0 and lower -->
<meta-data
android:name="android.support.PARENT_ACTIVITY"

android:value="com.freshdesk.mobihelp.activity.SolutionArticleListActivity"
/>
</activity>
<activity

662

Advanced Topics/Under The Hood

android:name="com.freshdesk.mobihelp.activity.SolutionArticleActivity"

android:parentActivityName="com.freshdesk.mobihelp.activity.SolutionArticleListActivit

android:theme="@style/Theme.Mobihelp"
android:configChanges="orientation|screenSize|keyboard|
keyboardHidden" >

<!-- Parent activity meta-data to support 4.0 and lower -->

<meta-data
android:name="android.support.PARENT_ACTIVITY"

android:value="com.freshdesk.mobihelp.activity.SolutionArticleListActivity"
/>
</activity>
<activity
android:name="com.freshdesk.mobihelp.activity.ConversationActivity"

android:parentActivityName="com.freshdesk.mobihelp.activity.SolutionArticleListActivit
android:theme="@style/Theme.Mobihelp"
android:windowSoftInputMode="adjustResize|stateHidden" >
<!-- Parent activity meta-data to support 4.0 and lower -->
<meta-data
android:name="android.support.PARENT_ACTIVITY"

android:value="com.freshdesk.mobihelp.activity.SolutionArticleListActivity"
/>
</activity>
<activity
android:name="com.freshdesk.mobihelp.activity.AttachmentHandlerActivity"
android:configChanges="keyboardHidden|orientation|screenSize"

android:parentActivityName="com.freshdesk.mobihelp.activity.SolutionArticleListActivit
android:theme="@style/Theme.Mobihelp" >
<!-- Parent activity meta-data to support 4.0 and lower -->
<meta-data
android:name="android.support.PARENT_ACTIVITY"

android:value="com.freshdesk.mobihelp.activity.SolutionArticleListActivity"
/>
</activity>

663

Advanced Topics/Under The Hood

<service android:name="com.freshdesk.mobihelp.service.MobihelpService" /

>

<receiver android:name="com.freshdesk.mobihelp.receiver.ConnectivityReceiver"

>

<intent-filter>
<action android:name="android.net.conn.CONNECTIVITY_CHANGE" />
</intent-filter>
</receiver>
</application>

</manifest>

Well need to add the <uses-permission> tags and all of the contents of the
<application> tag to our manifest file. Codename One provides the following build
hints for these:
1. android.xpermissions - For your <uses-permission> directives. Add a
build hint with name android.xpermissions , and for the value, paste the
actual <uses-permission> XML tag.
2. android.xapplication - For the contents of your <application> tag.

Proguard Config
For the release build, well also need to inject some proguard configuration so that
important classes dont get stripped out at build time. The FreshDesk SDK instructions
state:
If you use Proguard, please make sure you have the following included
in your projects proguard-project.txt
-keep class android.support.v4.** { *; }
-keep class android.support.v7.** { *; }

In addition, if you look at the proguard-project.txt file inside the Mobihelp SDK,
youll see the rules:
-keep public class * extends android.app.Service

664

Advanced Topics/Under The Hood

-keep public class * extends android.content.BroadcastReceiver
-keep public class * extends android.app.Activity
-keep public class * extends android.preference.Preference
-keep public class

com.freshdesk.mobihelp.exception.MobihelpComponentNotFoundException

-keepclassmembers class * implements android.os.Parcelable {

public static final android.os.Parcelable$Creator *;
}

Well want to merge this and then

android.proguardKeep of our project.

paste

them

into

the

build

hint

Troubleshooting Android Stuff

If, after doing all this, your project fails to build, you can enable the "Include Source"
option of the build server, then download the source project, open it in Eclipse or
Android Studio, and debug from there.

14.14.Part 2: Implementing the iOS Native Code

Part 1 of this tutorial focused on the Android native integration. Now well shift our focus
to the iOS implementation.
After selecting "Generate Native Interfaces" for our "MobihelpNative" class, youll find
a native/ios directory in your project with the following files:
1. com_codename1_freshdesk_MobihelpNativeImpl.h

47

2. com_codename1_freshdesk_MobihelpNativeImpl.m

48

These files contain stub implementations corresponding to our MobihelpNative

class.
49

We make use of the API docs to see how the native SDK needs to be wrapped. The
method names arent the same. E.g. instead of a method showFeedback() , it has
a message -presentFeedback:
47

https://github.com/shannah/cn1-freshdesk/blob/master/cn1-freshdesk-demo/native/ios/

com_codename1_freshdesk_MobihelpNativeImpl.h
48
https://github.com/shannah/cn1-freshdesk/blob/master/cn1-freshdesk-demo/native/ios/
com_codename1_freshdesk_MobihelpNativeImpl.m
49
http://developer.freshdesk.com/mobihelp/ios/api/

665

Advanced Topics/Under The Hood

We more-or-less just follow the iOS integration guide
key points include:

50

for wrapping the API. Some

1. Remember to import the Mobihelp.h file in your header file:

#import "Mobihelp.h"

2. Similar to our use of runOnUiThread() in Android, we will wrap all of our API
calls in either dispatch_async() or dispatch_sync() calls to ensure that
we are interacting with the Mobihelp API on the apps main thread rather than the
Codename One EDT.
3. Some methods/messages in the Mobihelp SDK require us to pass a
UIViewController as a parameter. In Codename One, the entire application
uses a single UIViewController: CodenameOne_GLViewController . You can
obtain a reference to this using the [CodenameOne_GLViewController
instance] message. We need to import its header file:
#import "CodenameOne_GLViewController.h"

As an example, lets look at the showFeedback() method:

-(void)showFeedback{
dispatch_async(dispatch_get_main_queue(), ^{
[[Mobihelp sharedInstance] presentFeedback:
[CodenameOne_GLViewController instance]];
});
}

14.14.1.Using the MobihelpNativeCallback

We described earlier how we created a static method on the
MobihelpNativeCallback class so that native code could easily fire a callback
method. Now lets take a look at how this looks from the iOS side of the fence. Here is
the implementation of getUnreadCountAsync() :
-(void)getUnreadCountAsync:(int)param{
50

http://developer.freshdesk.com/mobihelp/ios/integration_guide/#getting-started

666

Advanced Topics/Under The Hood

dispatch_async(dispatch_get_main_queue(), ^{

[[Mobihelp sharedInstance] unreadCountWithCompletion:^(NSInteger

count){

com_codename1_freshdesk_MobihelpNativeCallback_fireUnreadUpdatesCallback___int_int_int(
param, 3 /*SUCCESS*/, count);
}];
});

In
our
case
the
iOS
SDK
version
of
this
method
is
+unreadCountWithCompletion: which takes a block (which is like an anonymous
function) as a parameter.
The callback to our Codename One function occurs on this line:

com_codename1_freshdesk_MobihelpNativeCallback_fireUnreadUpdatesCallback___int_int_int(C
param, 3 /*SUCCESS*/, count);

Some things worth mentioning here:

1. The
method
name
is
the
result
of
taking
the
FQN
( com.codename1.freshdesk.MobihelpNativeCallback.fireUpdateUnreadUpdates
int, int) ) and replacing all . characters with underscores, suffixing two
underscores after the end of the method name, then appending _int once for
each of the int arguments.
2. We also need to import the header file for this class:
#import "com_codename1_freshdesk_MobihelpNativeCallback.h"

14.14.2.Bundling Native iOS SDK

Now that we have implemented our iOS native interface, we need to bundle the
Mobihelp iOS SDK into our project. There are a few different scenarios you may face
when looking to include a native SDK:
1. The SDK includes .bundle resource files. In this case, just copy the .bundle
file(s) into your native/ios directory.
2. The SDK includes .h header files. In this case, just copy the .h file(s) into your
native/ios directory.
667

Advanced Topics/Under The Hood

3. The SDK includes .a files. In this case, just copy the .a file(s) into your native/
ios directory.
4. The SDK includes .framework files. This is a bit tricker as Codename One
doesnt support simply copying the .framework files inside your project. In this
case you need to perform the following:
5. Right click on the .framework file (if you are using OS X) and select "Show
Package Contents".
6. Find the "binary" file within the framework, and copy it into your native/ios
directory - but rename it libXXX.a (where XXX is the name of the binary).
7. Copy all .h files from the framework into your native/ios directory.
8. Update all
#import
statements in the headers from
#import
<FrameworkName/FileName.h> format to simply #import "FileName.h"
The FreshDesk SDK doesnt include any
.framework
files, so
we dont need to worry about that last scenario. We simply
51
download the iOS SDK , copy the libFDMobihelpSDK.a , Mobihelp.h .
MHModel.bundle , MHResources.bundle , and MHLocalization/en.proj/
MHLocalizable.strings into native/ios .

14.14.3.Troubleshooting iOS
If you run into problems with the build, you can select "Include Sources" in the build
server to download the resulting Xcode Project. You can then debug the Xcode project
locally, make changes to your iOS native implementation files, and copy them back into
your project once it is building properly.

14.14.4.Adding Required Core Libraries and Frameworks

The iOS integration guide for the FreshDesk SDK lists the following core frameworks
as dependencies:

51

https://s3.amazonaws.com/assets.mobihelp.freshpo.com/sdk/mobihelp_sdk_ios.zip

668

Advanced Topics/Under The Hood

Figure 14.25. IOS link options

We can add these dependencies to our project using the ios.add_libs build hint.
E.g.

Figure 14.26. iOSs "add libs" build hint

I.e. we just list the framework names separated by semicolons. Notice that my list in
the above image doesnt include all of the frameworks that they list because many of
the frameworks are already included by default (I obtained the default list by simply
building the project with "include sources" checked, then looked at the frameworks that
were included).

14.15.Part 3 : Packaging as a .cn1lib

During the initial development, I generally find it easier to use a regular Codename One
project so that I can run and test as I go. But once it is stabilized, and I want to distribute
the library to other developers, I will transfer it over to a Codename One library project.
This general process involves:
1. Create a Codename One Library project.
2. Copy the .java files from my original project into the library project.
3. Copy the native directory from the original project into the library project.
4. Copy
the
relevant
build
hints
from
the
original
codenameone_settings.properties
file into the library
codenameone_library_appended.properties file.
669

projects
projects

Advanced Topics/Under The Hood

In the case of the FreshDesk .cn1lib, I modified the original projects build script to
generate and build a library project automatically. But that is beyond the scope of this
tutorial.

14.16.Building Your Own Layout Manager

A Layout

52

contains all the logic for positioning Codename One components.

It essentially traverses a Codename One Container

absolutely based on internal logic.

53

and positions components

When we build the layout we need to take margin into consideration and make sure to
add it into the position/size calculations. Building a layout manager involves two simple
methods: layoutContainer & getPreferredSize .
layoutContainer is invoked whenever Codename One decides the container
needs rearranging, Codename One tries to avoid calling this method and only invokes
it at the last possible moment. Since this method is generally very expensive (imagine
the recursion with nested layouts). Codename One just marks a flag indicating layout
is "dirty" when something important changes and tries to avoid "reflows".
getPreferredSize allows the layout to determine the size desired for the container.
This might be a difficult call to make for some layout managers that try to provide both
flexibility and simplicity.
Most of FlowLayout bugs stem from the fact that this method is just impossible to
implement correctly & efficiently for all the use cases of a deeply nested FlowLayout .
The size of the final layout wont necessarily match the requested size (it probably
wont) but the requested size is taken into consideration, especially when scrolling and
also when sizing parent containers.
This is a layout manager that just arranges components in a center column aligned to
the middle. We then show the proper usage of margin to create a stair like effect with
this layout manager:
class CenterLayout extends Layout {

public void layoutContainer(Container parent) {

int components = parent.getComponentCount();

Style parentStyle = parent.getStyle();

52
53

https://www.codenameone.com/javadoc/com/codename1/ui/layouts/Layout.html
https://www.codenameone.com/javadoc/com/codename1/ui/Container.html

670

Advanced Topics/Under The Hood

int centerPos = parent.getLayoutWidth() / 2 +

parentStyle.getMargin(Component.LEFT);

int y = parentStyle.getMargin(Component.TOP);
boolean rtl = parent.isRTL();

for (int iter = 0; iter < components; iter++) {

Component current = parent.getComponentAt(iter);

Dimension d = current.getPreferredSize();
Style currentStyle = current.getStyle();

int marginRight = currentStyle.getMarginRight(rtl);

int marginLeft = currentStyle.getMarginLeft(rtl);
int marginTop = currentStyle.getMarginTop();

int marginBottom = currentStyle.getMarginBottom();

current.setSize(d);

int actualWidth = d.getWidth() + marginLeft + marginRight;

current.setX(centerPos - actualWidth / 2 + marginLeft);

y += marginTop;
current.setY(y);
y += d.getHeight() + marginBottom;

public Dimension getPreferredSize(Container parent) {

int components = parent.getComponentCount();
Style parentStyle = parent.getStyle();

int height = parentStyle.getMargin(Component.TOP) +

parentStyle.getMargin(Component.BOTTOM);

int marginX = parentStyle.getMargin(Component.RIGHT) +

parentStyle.getMargin(Component.LEFT);
int width = marginX;

for (int iter = 0; iter < components; iter++) {

Component current = parent.getComponentAt(iter);

Dimension d = current.getPreferredSize();
Style currentStyle = current.getStyle();
width = Math.max(d.getWidth() + marginX +

currentStyle.getMargin(Component.RIGHT)
+ currentStyle.getMargin(Component.LEFT), width);
height += currentStyle.getMargin(Component.TOP) +
d.getHeight()
+ currentStyle.getMargin(Component.BOTTOM);
}
Dimension size = new Dimension(width, height);

return size;

Form hi = new Form("Center Layout", new CenterLayout());

671

Advanced Topics/Under The Hood

for(int iter = 1 ; iter < 10 ; iter++) {

Label l = new Label("Label: " + iter);

l.getUnselectedStyle().setMarginLeft(iter * 3);
l.getUnselectedStyle().setMarginRight(0);
}

hi.add(l);

hi.add(new Label("Really Wide Label Text!!!"));

hi.show();

Figure 14.27. Center layout staircase effect with margin

672

Advanced Topics/Under The Hood

14.16.1.Porting a Swing/AWT Layout Manager

54

The GridBagLayout was ported to Codename One relatively easily considering the
complexity of that specific layout manager. Here are some tips you should take into
account when porting a Swing/AWT layout manager:
1. Codename One doesnt have Insets , we added some support for them in order
to port GridBag but components in Codename One have a margin they need to
consider instead of the Insets (the padding is in the preferred size and is thus
hidden from the layout manager).
2. AWT layout managers also synchronize a lot on the AWT thread. This is no longer
necessary since Codename One is single threaded, like Swing.
3. AWT considers the top left position of the Container to be 0,0 whereas
Codename One considers the position based on its parent Container . The top
left position in Codename One is getX() , getY() .
Other than those things its mostly just fixing method and import statements, which are
slightly different. Pretty trivial stuff.

54

https://www.codenameone.com/javadoc/com/codename1/ui/layouts/GridBagLayout.html

673

Chapter15.Signing, Certificates &

Provisioning
In this section we attempt to explain how to acquire certificates for the various platforms
and how to set them up.
The good news is that this is usually a "one time issue" and once its done the work
becomes easier (except for the case of iOS where a provisioning profile should be
maintained).

15.1.Common Terms In Signing & Distribution

This section uses some terms that you might not be familiar with if you havent used
cryptography or built mobile apps before. Here is a quick "FAQ" covering some common
terms/concepts in this section.

15.1.1.What Is A Certificate?
Certificates use cryptographic principals to "sign" data (e.g. an application). Think of
them as you would think of a company stamp, you use them to sign an app so users
know who its from.

15.1.2.What Is Provisioning?
Provisioning provides the hints/guidelines for the application install. E.g. if an
application needs some service from the OS such as push it can usually request that
with provisioning.
In iOS provisioning is separate from the app and you need to also define the devices
supported by the app during development.

15.1.3.Whats a Signing Authority?

Normally certificates are issued by a signing authority which is a body that certifies
that you are who you say you are. Apple issues certificates for iOS and is in effect a
signing authority.
Android uses self signed certificates which dont use a signing authority so anyone can
ship an Android app.
674

Signing, Certificates & Provisioning

The logic with the Android approach is that a signature indicates that you are the same
person who previously shipped the app. Hence an app will be updated only with the
exact same certificate.

15.1.4.What is UDID?
The UDID is the Universal Device Identifier. It identifies mobile devices uniquely,
notice that some operating systems e.g. iOS block access to this value due to privacy
concerns.
You need the iOS device UDID value during development to add the device into the
list of allowed devices.
Dont use an app to get the UDID!
Most return the wrong value, the official way to get the UDID is
thru itunes. We can also recommend trying http://get.udid.io/ which
seems to work rather well

15.1.5.Should I Reuse the Same Certificate for All Apps?

For iOS yes. Its designed to work in that way.
We would recommend it for all platforms for simplicity but some developers prefer
creating per-application certificates for Android. The advantage here is that you can
transfer ownership of the application later on without giving away what is effectively
"you house keys".

15.2.iOS Signing Wizard

Codename One features a wizard to generate certificates/provisioning for iOS without
requiring a Mac or deep understanding of the signing process for iOS. There is still
support for manually generating the P12/provisioning files when necessary but for most
intents and purposes using the wizard will simplify this error prone process significantly.
To generate your certificates and profiles, open projects properties and click on "iOS"
in the left menu. This will show the "iOS Signing" panel that includes fields to select
your certificates and mobile provisioning profiles.

675

Signing, Certificates & Provisioning

Figure 15.1. Netbeans iOS Signing properties panel

If you already have valid certificates and profiles, you can just enter their locations here.
If you dont, then you can use the wizard by clicking the Generate button in the lower
part of the form.

15.2.1.Logging into the Wizard

After clicking Generate youll be shown a login form. Log into this form using your
iTunes Connect user ID and password. NOT YOUR CODENAME ONE LOGIN.

676

Signing, Certificates & Provisioning

Figure 15.2. Wizard login form

15.2.2.Selecting Devices
Once you are logged in you will be shown a list of all of the devices that you currently
have registered on your Apple developer account.

677

Signing, Certificates & Provisioning

Figure 15.3. Devices form

Select the ones that you want to include in your provisioning profile and click next.
Apple supports up to 100 devices for testing purposes so if you want
to install the built app on your device you need to add it here

678

Signing, Certificates & Provisioning

Figure 15.4. After selecting devices

If you dont have any devices registered yet, you can click the "Add New Device" button,
which will prompt you to enter the UDID for your device.

15.2.3.Decisions & Edge Cases

If you already have iOS P12 development/distribution certificates
you should reuse them for all your apps from that account and you
shouldnt regenerate them

679

Signing, Certificates & Provisioning

After you click Next on the device form, the wizard checks to see if you already have
a valid certificate. If your project already has a valid certificate and it matches the
one that is currently active in your apple developer account, then it will just use the
same certificate. If the certificate doesnt match the currently-active one, or you havent
provided a certificate, you will be prompted to overwrite the old certificate with a new
one.

Figure 15.5. Prompt to overwrite existing certificate

680

Signing, Certificates & Provisioning

Figure 15.6. Prompt to overwrite other certificate

The same decision need to be made twice: Once for the development certificate, and
once for the Apptore certificate.
You can revoke a certificate when you have an application in the
store shipping with said certificate!
1
This wont affect the shipping app see this .
1

http://stackoverflow.com/questions/6320255/if-i-revoke-an-existing-distribution-certificate-will-it-mess-up-

anything-with

681

Signing, Certificates & Provisioning

Why Two Certificates?

A typical iOS app has at least two certificates:
Development - this is used during development and cant be shipped to 3rd
parties. An application signed with this certificate can only be installed on one
of the up to 100 devices listed above.
Distribution - this is used when you are ready to upload your app to itunes
whether for final shipping or beta testing. Notice that you cant install a
distribution build on your own device. You need to upload it to itunes.
There are two push certificates, they are separate from the signing
certificates. Dont confuse them!
They are used to authenticate with Apple when sending push messages.

15.2.4.App IDs and Provisioning Profiles

The next form in the wizard asks for your apps bundle ID. This should have been prefilled, but you can change the app ID to a wildcard ID if you prefer.

682

Signing, Certificates & Provisioning

Figure 15.7. Enter the app bundle ID

Wildcard Card Provisioning

Wildcard ids such as com.mycompany.\* or even \* allow you to create one
generic certificate to use with all applications. This is remarkably useful for the
global settings dialog and allows you to create an app without launching the
wizard. Notice that wildcards apps cant use features such as push etc.

683

Signing, Certificates & Provisioning

You can set the global defaults for the IDE by going to IDE settings/preferences
and setting default values e.g.:

Figure 15.8. Setting the development certificate and a global \*

provisioning profile allows you to create a new app and built
it to device without running the certificate wizard. Notice that
you will need to run it when going into production

15.2.5.Installing Files Locally

Once the wizard is finished generating your provisioning profiles, you should click
"Install Locally", which will open a file dialog for you to navigate to a folder in which to
store the generated files.

684

Signing, Certificates & Provisioning

Figure 15.9. Install files locally

685

Signing, Certificates & Provisioning

Figure 15.10. Select directory to save files in

686

Signing, Certificates & Provisioning

Figure 15.11. Final Done Message

You can see the password for the P12 files in the
codenameone_settings.properties file. You can use the
values defined there when creating a new application

15.2.6.Building Your App

After selecting your local install location, and closing the wizard, you should see the
fields of the "iOS Signing" properties panel filled in correctly. You should now be able
to send iOS debug or Appstore builds without the usual hassles.
687

Signing, Certificates & Provisioning

Figure 15.12. Filled in signing panel after wizard complete

15.3.Advanced iOS Signing

You should use the certificate wizard, especially if you dont have a
Mac. This section is here mostly for reference and edge cases that
dont work with the certificate wizard
iOS signing has two distinct modes: App Store signing which is only valid for distribution
via iTunes (you wont be able to run the resulting application without submitting it to
Apple) and development mode signing.
You have two major files to keep track of:
1. Certificate - your signature
2. Provisioning Profile - details about the application and who is allowed to execute it
You need two versions of each file (4 total files) one pair is for development and the
other pair is for uploading to the itunes App Store.
You need to use a Mac in order to create a certificate file for iOS

688

Signing, Certificates & Provisioning

The first step you need to accomplish is signing up as a developer to Apples iOS
2
development program , even for testing on a device this is required!
This step requires that you pay Apple on an annual basis.
The Apple website will guide you through the process of applying for a certificate at
the end of this process you should have a distribution and development certificate pair.
3
After that point you can login to the iOS provisioning portal where there are plenty
of videos and tutorials to guide you through the process. Within the iOS provisioning
portal you need to create an application ID and register your development devices.
You can then create a provisioning profile which comes in two flavors:
Distribution - for building the release version of your application
Development - the development provisioning profile needs to contain the devices
on which you want to test.
You can then configure the 4 files in the IDE and start sending builds to the Codename
One cloud.

15.4.Provisioning Profile & Certificates Visual Guide

One of the hardest parts in developing for iOS is the certificate & provisioning process.
In this step by step guide we walk over the manual certificate generation process. Notice
that the UI for the Apple website changes occasionally but the basic process remains
the same
Start by logging in to the iOS-provisioning portal

Figure 15.13. Login for the iOS provisioning portal

2
3

http://developer.apple.com/
https://developer.apple.com/ios/manage/overview/index.action

689

Signing, Certificates & Provisioning

In the certificates section you can download your development and distribution
certificates.

Figure 15.14. Download development provisioning profile

Figure 15.15. Download distribution provisioning profile

In the devices section add device ids for the development devices you want to support.
Notice no more than 100 devices are supported!

690

Signing, Certificates & Provisioning

Figure 15.16. Add devices

Create an application id; it should match the package identifier of your application
perfectly!

Figure 15.17. Create application id

Create a provisioning profile for development, make sure to select the right app and
make sure to add the devices you want to use during debug.

691

Signing, Certificates & Provisioning

Figure 15.18. Create provisioning profile step 1

Figure 15.19. Create provisioning profile step 2

Refresh the screen to see the profile you just created and press the download button
to download your development provisioning profile.

692

Signing, Certificates & Provisioning

Figure 15.20. Create provisioning profile step 3

Create a distribution provisioning profile; it will be used when uploading to the app store.
There is no need to specify devices here.

Figure 15.21. Create distribution provisioning profile

Download the distribution provisioning profile.

693

Signing, Certificates & Provisioning

Figure 15.22. Download distribution provisioning profile

We can now import the cer files into the key chain tool on a Mac by double clicking the
file, on Windows the process is slightly more elaborate

Figure 15.23. Import cer files

We can export the p12 files for the distribution and development profiles through the
keychain tool

694

Signing, Certificates & Provisioning

Figure 15.24. Export p12 files

In the IDE we enter the project settings, configure our provisioning profile, the password
we typed when exporting and the p12 certificates. It is now possible to send the build
to the server.

Figure 15.25. IOS Project Settings

15.4.1.iOS Code Signing Failure Checklist

Below is a list of common issues when singing and a set of suggestions for things to
check. Notice that some of these signing failures will sometimes manifest themselves
during build and sometimes will manifest during the install of the application.
695

Signing, Certificates & Provisioning

Most of these issues arent applicable when using the wizard e.g. a
Mac isnt required for the certificate wizard as it uses the Codename
One cloud
You must use a Mac to generate P12 certificates manually. The only workaround
we found is the certificate wizard!
Notice that this is something you need to do once a year (generate P12), you will
also need a Mac to upload your final app to the store at this time.
When exporting the P12 certificate make sure that you selected BOTH the public
and the private keys as illustrated here. If you only see one entry (no private key)
then you created the CSR (singing request) on a different machine than the one
where you imported the resulting CER file.

Figure 15.26. p12 export

Make sure the package matches between the main preferences screen in the IDE
and the iOS settings screen.

Figure 15.27. Package ID matching App ID

Make sure the prefix for the app id in the iOS section of the preferences matches
the one you have from Apple

696

Signing, Certificates & Provisioning

Figure 15.28. App prefix

Make sure your provisioning profiles app id matches your package name or is a *
provisioning profile. Both are sampled in the pictures below, notice that you would
need an actual package name for push/in-app-purchase support as well as for app
store distribution.

697

Signing, Certificates & Provisioning

Figure 15.29. The star (*) Provisioning Profile

698

Signing, Certificates & Provisioning

Figure 15.30. Provisioning Profile with app id

Make sure the certificate and provisioning profile are from the same source (if
you work with multiple accounts), notice that provisioning profiles and certificates
expire so you will need to regenerate provisioning when your certificate expires or
is revoked.
If you declare push in the provisioning profile then ios.includePush (in the build
arguments) MUST be set to true, otherwise it MUST be set to false (see pictures
below). Notice that this should be configured via the UI in the iOS section.

699

Signing, Certificates & Provisioning

Figure 15.31. Include push build hint

15.5.Android
Signing Android applications is trivial when compared to the pain of iOS signing.
The NetBeans and Eclipse plugins have a simple wizard to generate the certificate that
you can launch by pressing this button:

Figure 15.32. Android keystore generation wizard

700

Signing, Certificates & Provisioning

Then fill out your details and password in the form:

Figure 15.33. UI for Android certificate details

This will seamlessly generate a certificate for your project, you can reuse it for other
projects as well.

15.5.1.Generating an Android Certificate Manually

You need the JDKs keytool executable (it should be under the JDKs bin directory) and
execute the following command:
keytool -genkey -keystore Keystore.ks -alias [alias_name] -keyalg RSA keysize 2048 -validity 15000 -dname "CN=[full name], OU=[ou], O=[comp],
L=[City], S=[State], C=[Country Code]" -storepass [password] -keypass
[password]

701

Signing, Certificates & Provisioning

The elements in the brackets should be filled up based on this:
Alias: [alias_name] (just use your name/company name without spaces)
Full name: [full name]
Organizational Unit: [ou]
Company: [comp]
City: [City]
State: [State]
CountryCode: [Country Code]
Password: [password] (we expect both passwords to be identical)

Executing the command will produce a Keystore.ks file in that directory which you need
to keep since if you lose it you will no longer be able to upgrade your applications! Fill
in the appropriate details in the project properties or in the CodenameOne section in
the Netbeans preferences dialog.
For more details see http://developer.android.com/guide/publishing/app-signing.html

15.6.RIM/BlackBerry
4

You can now get signing keys for free from Blackberry by going here . Once you
obtain the certificates you need to install them on your machine (you will need the
Blackberry development environment for this). You will have two files: sigtool.db
and sigtool.csk on your machine (within the JDE directory hierarchy). We need
them and their associated password to perform the signed build for Blackberry
application.

15.7.J2ME
Currently signing J2ME applications isnt supported. You can use tools such as the
Sprint WTK to sign the resulting jad / jar produced by Codename One.

https://www.blackberry.com/SignedKeys/

702

Chapter16.Appendix: Working With iOS

16.1.The iOS Screenshot/Splash Screen Process
iOS apps seem to start almost instantly in comparison to Android apps.
There is a trick to that, iOS applications have a file traditionally called Default.png
that includes a 320x480 pixel image of the first screen of the application. This creates
an "illusion" of the application instantly coming to life and filling up with data, this is
1
rather clever but is a source trouble as the platform grows .
You can disable the screenshot process entirely with the
ios.fastBuild=true build hint. This will only apply for debug
builds so you dont need to worry about accidentally forgetting it in
production.
The screenshot process was a pretty clever workaround but as Apple introduced the
retina display 640x960 it required a higher resolution [email protected] file, then
2
it added the iPad, iPad Retina and iPhone 5 iPhone 6 & 6+ all of which required
images of their own.
To make matters worse iPad apps (and iPhone 6+ apps) can be launched in landscape
mode so thats two more resolutions for the horizontal orientation iPad. Overall as of
this writing (or until Apple adds more resolutions) we need 10 screenshots for a typical
iOS app:

Table 16.1. iOS Device Screenshot Resolutions

Resolution

File Name

Devices

320x480

Default.png

iPhone 3gs

640x960

[email protected]

iPhone 4x

640x1136

[email protected] iPhone 5x

1024x768

DefaultPortrait.png

Non-retina ipads in portrait

mode

768x1024

DefaultLandscape.png

Non-retina ipads in
landscape mode

Apple provided another trick with XIB files starting with iOS 8 but that doesnt apply to games or
Codename One. It has its own set of problems
2
slightly larger screen and different aspect ratio

703

Appendix: Working With iOS

Resolution

File Name

Devices

2048x1536

[email protected]

Retina ipads in portrait

mode

1536x2048

[email protected]

Retina ipads in landscape

mode

750x1334

[email protected] iPhone 6

1242x2208

[email protected] iPhone 6 Plus Portrait

2208x1242

[email protected]

iPhone 6 Plus Landscape

You can predefine any of these files within the native/ios

directory in your project. If the build server sees a file matching that
exact name it will not generate a screenshot for that resolution
Native iOS developers literally run their applications 10 times with blank data to
grab these screenshots every time they change something in the first view of their
application!
With Codename One this will not be feasible since the fonts and behavior might not
match the device. Thus Codename One runs the application 10 times in the build
servers, grabs the right sized screenshots in the simulator and then builds the app!
This means the process of the iPhone splash screen is almost seamless to the
developer, however like every abstraction this too leaks.
The biggest problem developers have with this approach is for apps that use a web
browser or native maps in the first screen of their app. This wont work well as those
are native widgets. They will look different during the screenshot process.
Another problem is with applications that require a connection immediately on startup,
this can fail for the build process.
A solution to both problems is to create a special case for the first launch of the app
where no data exists. This will setup the screenshot process correctly and let you
proceed with the app as usual.

16.1.1.Size
One of the first things we ran into when building one of our demos was a case where
an app that wasnt very big in terms of functionality took up 30mb!
704

Appendix: Working With iOS

After inspecting the app we discovered that the iPad retina PNG files were close to
5mb in size
Since we had 2 of them (landscape and portrait) this was the main problem.
The iPad retina is a 2048x1536 device and with the leather theme the PNG images are
almost impossible to compress because of the richness of details within that theme.
This produced the huge screenshots that ballooned the application.

16.1.2.Mutable first screen

A very common use case is to have an application that pops up a login dialog on first
run. This doesnt work well since the server takes a picture of the login screen and the
login screen will appear briefly for future loads and will never appear again.

16.1.3.Unsupported component
One of the biggest obstacles is with heavyweight components, e.g. if you use a
browser or maps on the first screen of the app you will see a partially loaded/distorted
3
MapComponent and the native webkit browser obviously cant be rendered properly
by our servers.
The workaround for such issues is to have a splash screen that doesnt include any
of the above. Its OK to show it for a very brief amount of time since the screenshot
process is pretty fast.

16.2.Local Notifications on iOS and Android

Local notifications are similar to push notifications, except that they are initiated locally
by the app, rather than remotely. They are useful for communicating information to the
user while the app is running in the background, since they manifest themselves as
pop-up notifications on supported devices.

16.2.1.Sending Notifications
The process for sending a notification is:
1. Create a LocalNotification
notification.
3
4

object with the information you want to send in the

https://www.codenameone.com/javadoc/com/codename1/maps/MapComponent.html
https://www.codenameone.com/javadoc/com/codename1/notifications/LocalNotification.html

705

Appendix: Working With iOS

2. Pass the object to Display.scheduleLocalNotification() .
Notifications can either be set up as one-time only or as repeating.

Example Sending Notification

LocalNotification n = new LocalNotification();

n.setId("demo-notification");
n.setAlertBody("It's time to take a break and look at me");
n.setAlertTitle("Break Time!");
n.setAlertSound("beep-01a.mp3");
Display.getInstance().scheduleLocalNotification(
n,

System.currentTimeMillis() + 10 * 1000, // fire date/time

LocalNotification.REPEAT_MINUTE

frequency

);

The resulting notification will look like

706

// Whether to repeat and what

Appendix: Working With iOS

Figure 16.1. Resulting notification in iOS

16.2.2.Receiving Notifications
The API for receiving/handling local notifications is also similar to
push. Your applications main lifecycle class needs to implement the
com.codename1.notifications.LocalNotificationCallback
interface
which includes a single method:
707

Appendix: Working With iOS

public void localNotificationReceived(String notificationId)

The notificationId parameter will match the id value of the notification as set
using LocalNotification.setId() .

Example Receiving Notification

public class BackgroundLocationDemo implements LocalNotificationCallback {
//...

public void init(Object context) {

}

//...

public void start() {

//...

}
public void stop() {
}

//...

public void destroy() {

}

//...

public void localNotificationReceived(String notificationId) {

System.out.println("Received local notification "+notificationId);

localNotificationReceived() is only called when the user

responds to the notification by tapping on the alert. If the user doesnt
click on the notification, then this event handler will never be fired.

16.2.3.Canceling Notifications
Repeating notifications will continue until they are canceled by the app. You can cancel
a single notification by calling:
Display.getInstance().cancelLocalNotification(notificationId);

708

Appendix: Working With iOS

Where notificationId is the string id that was set for the notification using
LocalNotification.setId() .

16.3.Push Notifications
Push notification allows us to send a notification to a device while the application
might be in the background. This is important both as a marketing tool and as a basic
communications device.

Why Push & Not Polling?

Polling the server or long polling seem like sensible time proven strategies.
However, there are many complexities related to that strategy in mobile phones.
The biggest problem is that a polling application will be killed by the OS as it
is sent to the background to conserve OS resources. While this might work in
some OSs and some cases this isnt something you can rely on. E.g. Android
6+ tightened the background process behavior significantly.
The other issue is battery life, new OSs expose battery wasting applications
and as a result might trigger uninstalls. This makes even foreground polling less
appealing.
The final issue is networking, polling is problematic when a device is connected
via cellular connection and switching towers. Push might have issues as well,
but its hard to beat the QA/optimization done by Apple/Google.

16.3.1.What Is Push?
If you are new to mobile development then you heard a lot of buzzwords and very little
substance. The problem is that iOS and Android have very different ideas of what push
is and should be.
For Android push is a communication system that the server can initiate. E.g. the cloud
can send any packet of data and the device can process it in rather elaborate ways.
For iOS push is mostly a visual notification triggered by the server to draw attention to
new information inside an app.
709

Appendix: Working With iOS

These dont sound very different until you realize that in Android you can send/receive
a push without the awareness of the end user. In iOS a push notification is displayed
to the user, but the app might be unaware of it!
iOS will only deliver the push notification to the app, if it is running or
if the user clicked the push notification popup!
Codename One tried to make both OSs "feel" similar so background push calls act the
same in iOS and Android as a result.
You shouldnt push important data, push is lossy and shouldnt
include a payload that MUST arrive!
Instead use push as a flag to indicate that the server has additional
data for the app to fetch

16.3.2.The Push Bureaucracy - Android

Android Push goes thru Google servers and to do that we need to register with Google
to get keys for server usage.
We need two important values: GCM_SENDER_ID & GCM_SERVER_API_KEY . The
former is used in the client and the latter value is used to push from the server code.
To generate these values we need a Google cloud project. We go over the process of
generating a cloud project in the Google+ login section here.
To generate those just go to https://developers.google.com/mobile/add and click pick
a platform:

710

Appendix: Working With iOS

Figure 16.2. Click "pick a platform"

Select Android App

Figure 16.3. Select "Android App"

Google introduced support for sending GCM messages to iOS
applications, this has nothing to do with the iOS native push we
discuss below
Enter the details for the app and the package
711

Appendix: Working With iOS

Figure 16.4. Enter the details for the app and the package
Click the Cloud Messaging option then click the Enable Google Cloud Messaging button

712

Appendix: Working With iOS

Figure 16.5. Click the "Cloud Messaging" option then click the
"Enable Google Cloud Messaging" button
You should now have the values for both
GCM_SENDER_ID
&
GCM_SERVER_API_KEY as illustrated below. Notice that the sender id is the numeric
key whereas the api key is the alpha-numeric key:

713

Appendix: Working With iOS

Figure 16.6. You should now have the values for both
GCM_SENDER_ID & GCM_SERVER_API_KEY

16.3.3.The Push Bureaucracy - iOS

Push on iOS is much harder to handle than the Android version, however we simplified
this significantly with the certificate wizard.
iOS push needs two additional P12 certificates.
Please notice that these are NOT the signing certificates!
They are completely different certificates that have nothing to do
with the build process!
The certificate wizard can generate these additional push certificates and do quite a
few other things if you just check this flag in the end of the wizard:

714

Appendix: Working With iOS

Figure 16.7. Enable Push in the certificate wizard

If you already have signing certificated defined for your app just skip
the certificate generation phase (answer no) the rest will work as
usual.
You can then install the push certificates locally and use them later on but there is an
easier way.
You need to host the push certificates in the cloud so they will be reachable by the push
servers, Codename One that for you seamlessly.
Once you go thru the wizard you should get an automated email containing information
about push and the location of the push certificates, it should start like this:

715

Appendix: Working With iOS

iOS Push certificates have been created for your app with bundle ID
com.mycompany.myapp.mypushdemo. Please file this email away for safe
keeping as you will need the details about the certificate locations and
passwords to use Push successfully in your apps.

Development Push Certificate URL:

https://codename-one-push-certificates.s3.amazonaws.com/
com.mycompany.myapp.mypushdemo_DevelopmentPush_LONG_UNIQUE_KEY.p12
Development Push Certificate Password: ssDfdsfer324
Production Push Certificate URL:
https://codename-one-push-certificates.s3.amazonaws.com/
com.mycompany.myapp.mypushdemo_ProductionPush_LONG_UNIQUE_KEY.p12
Production Push Certificate Password: ssDfdsfer324

The URLs and passwords are everything that you will need later on to get push working
on iOS. Notice that the wizard also performs a couple of other tasks specifically it sets
the ios.includePush build hint to true & adds push to the provisioning profile etc.
You can read more about the certificate wizard in the signing section

16.3.4.Push Client Code

Push has two distinct pieces, the device that receives the push notification (the client)
and the code that sends the push notification (either another device or more often the
server code).
The following code shows a simple push test client application, we go over the
significant pieces below:
public class PushDemo implements PushCallback {
private Form current;

private Resources theme;

private static final String MY_SERVER_URL = "https://.../";

private static final String GCM_SENDER_ID = "99999999999999";

public void init(Object context) {
}

theme = UIManager.initFirstTheme("/theme");

716

Appendix: Working With iOS

public void start() {

if(current != null){
current.show();

return;

Form hi = new Form("Push Test");

Display.getInstance().callSerially(() -> {
Hashtable metaData = new Hashtable();

metaData.put(com.codename1.push.Push.GOOGLE_PUSH_KEY,
GCM_SENDER_ID);
Display.getInstance().registerPush(metaData, true);
});
hi.show();
}
public void stop() {

current = Display.getInstance().getCurrent();
if(current instanceof Dialog) {

((Dialog)current).dispose();
current = Display.getInstance().getCurrent();

public void destroy() {

}

@Override

public void push(String value) {

}

Dialog.show("Received Push", value, "OK", null);

@Override

public void registeredForPush(String deviceId) {

// IMPORTANT: Notice that Push.getPushKey() != deviceId !!!

ConnectionRequest con = new ConnectionRequest(MY_SERVER_URL,

true);

con.addArgument("pushKey", Push.getPushKey());
NetworkManager.getInstance().addToQueue(con);

@Override

public void pushRegistrationError(String error, int errorCode) {

Dialog.show("Push Error", "" + error, "OK", null);

717

Appendix: Working With iOS

5

A client must implement the PushCallback interface in the main class of the
application (the one with the callback methods)!
This sample requires a server that will accept the device id. Push is challenging
without some central repository that will collect device IDs from the clients
You get the GCM_SENDER_ID value from Google as discussed above

We register push every time we start the application, this is expected behavior
since push details might change.
Notice that we wrap the call in a callSerially , this provides the first Form
with time to appear. This is important as the user can be prompted for permissions
at which point you wouldnt want that prompt to show on top of a blank screen.
This method is invoked when a push message is received, it can be invoked
multiple times for some cases
After registration push might still not be valid, it is only valid once this method is
invoked. While its not essential to register in the server at this point, its probably
what you should do.

16.3.5.Sending Push Messages

You can send a push message in many ways e.g. from another device or any type of
server but there are some values that you will need regardless of the way in which you
send the push message.
private static final String PUSH_TOKEN = "********-****-****-*****************";

The push token is a unique "key" that you can use to send push thru your Codename
One account. It allows you to send push messages without placing your Codename
One email or password into your source files.
You can get it by going to the Codename One build server dashboard at https://
www.codenameone.com/build-server.html and selecting the Account tab.
The token should appear at the bottom as such:

https://www.codenameone.com/javadoc/com/codename1/push/PushCallback.html

718

Appendix: Working With iOS

Figure 16.8. Push Token from the build server

The instructions for extracting the API key for Google are listed above.
private static final String GCM_SERVER_API_KEY = "**************************************";

When sending push to iOS devices we have two modes: - Production - Distribution
This allows you to debug the push related functionality without risking the possibility
of sending a push into a production app. Its important to send the values to the right
server during development/production.
private static final boolean ITUNES_PRODUCTION_PUSH = false;

iOS needs a certificate in order to send a push, this allows you to prove to Apples push
servers that you are who you claim to be (the author of the app).

719

Appendix: Working With iOS

These are not the signing certificates and are completely separate
from them!
You can obtain these two certificates (for development/appstore) via the certificate
wizard as explained above.
private static final String ITUNES_PRODUCTION_PUSH_CERT = "https://
domain.com/linkToP12Prod.p12";

private static final String ITUNES_PRODUCTION_PUSH_CERT_PASSWORD

= "ProdPassword";

private static final String ITUNES_DEVELOPMENT_PUSH_CERT = "https://

domain.com/linkToP12Dev.p12";

private static final String ITUNES_DEVELOPMENT_PUSH_CERT_PASSWORD

= "DevPassword";

Sending a Push Message From Codename One

While normally sending a push message to a device should involve a server code there
might be cases (e.g. instant messaging/social) where initiating a push from one client
to another makes sense.
6

To simplify these use cases we added the Push API. To use the Push API you need
the device key of the destination device to which you want to send the message. You
can get that value from the Push.getPushKey() method. Notice that you need that
value from the destination device and not the local device!
To send a message to another device just use:
String cert = ITUNES_DEVELOPMENT_PUSH_CERT;
String pass = ITUNES_DEVELOPMENT_PUSH_CERT_PASSWORD;
if(ITUNES_PRODUCTION_PUSH) {

cert = ITUNES_PRODUCTION_PUSH_CERT;
pass = ITUNES_PRODUCTION_PUSH_CERT_PASSWORD;

}
Push.sendPushMessage(PUSH_TOKEN, "Hello World",
ITUNES_PRODUCTION_PUSH, GCM_SERVER_API_KEY, cert, pass, 1,
deviceKey));

https://www.codenameone.com/javadoc/com/codename1/push/Push.html

720

Appendix: Working With iOS

This will send the push message "Hello World" to the device with the key deviceKey .
The 1 argument represents the standard push message type, we discuss push
message types below.

Sending Push Message From A Java or Generic Server

Sending a push message from the server is a more elaborate affair and might require
sending push messages to many devices in a single batch.
We can send a push message as an HTTP POST request to https://
push.codenameone.com/push/push. That URL accepts the following arguments:
token - your developer token to identify the account sending the push PUSH_TOKEN
device - one or more device keys to send the push to. You can send push to up to
500 devices with a single request type - the message type identical to the old set of supported types in the old push
servers
body - the body of the message
auth - the Google push auth key - GCM_SERVER_API_KEY
production - true / false whether to push to production or sandbox environment
in iOS - ITUNES_PRODUCTION_PUSH
certPassword
password
for
the
push
certificate
iOS
push
ITUNES_DEVELOPMENT_PUSH_CERT_PASSWORD
ITUNES_PRODUCTION_PUSH_CERT_PASSWORD

in
or

cert - http or https URL containing the push certificate for an iOS push ITUNES_DEVELOPMENT_PUSH_CERT or ITUNES_PRODUCTION_PUSH_CERT
We can thus send a push from Java EE using code like this:
URLConnection connection = new URL("https://push.codenameone.com/push/
push").openConnection();
connection.setDoOutput(true);
connection.setRequestMethod("POST");
connection.setRequestProperty("Content-Type", "application/x-www-formurlencoded;charset=UTF-8");
String cert = ITUNES_DEVELOPMENT_PUSH_CERT;
String pass = ITUNES_DEVELOPMENT_PUSH_CERT_PASSWORD;

721

Appendix: Working With iOS

if(ITUNES_PRODUCTION_PUSH) {

cert = ITUNES_PRODUCTION_PUSH_CERT;
pass = ITUNES_PRODUCTION_PUSH_CERT_PASSWORD;

}
String query = "token=" + PUSH_TOKEN +
"&device=" + deviceId1 +
"&device=" + deviceId2 +
"&device=" + deviceId3 +
"&type=1" +
"&auth=" + GCM_SERVER_API_KEY +
"&certPassword=" + URLEncoder.encode(pass, "UTF-8") +
"&cert=" + cert +
"&body=" + URLEncoder.encode(MESSAGE_BODY, "UTF-8") +
"&production=" + ITUNES_PRODUCTION_PUSH;

try (OutputStream output = connection.getOutputStream()) {

}

output.write(query.getBytes("UTF-8"));

int c = connection.getResponseCode();
// read response JSON

Notice that you can send a push to 500 devices. To send in larger batches you need
to split the push requests into 500 device batches.

Server JSON Responses

The push servers send responses in JSON form. Its crucial to parse and manage those
as they might contain important information.
If there is an error that isnt fatal such as quota exceeded etc. you will get an error
message like this:
{"error":"Error message"}

A normal response, will be an array with results:

[

{"id"="deviceId","status"="error","message"="Invalid Device ID"},

{"id"="cn1-gcm-nativegcmkey","status"="updateId", "newId"="cn1-gcmnewgcmkey"},
{"id"="cn1-gcm-okgcmkey","status"="OK"},
{"id"="cn1-gcm-errorkey","status"="error","message"="Server error
message"},
{"id"="cn1-ios-iphonekey","status"="inactive"},

722

Appendix: Working With iOS

]

There are several things to notice in the responses above:

If the response contains status=updateId it means that the GCM server wants
you to update the device id to a new device id. You should do that in the database
and avoid sending pushes to the old key
iOS doesnt acknowledge device receipt but it does send a status=inactive
result which you should use to remove the device from the list of devices
APNS (Apples push service) returns uppercase key results. This
means that code for managing the keys in your database must be
case insensitive
Apple doesnt always send back a result for a device being inactive
and might fail silently

Various Types of Push Messages

The type argument when sending a push exposes many OS specific capabilities.
Notice that on iOS push messages will only trigger the push method
if the app is in the foreground or if the user explicitly clicked the
message!
0 , 1 - The default push types, they work everywhere and present the string as
the push alert to the user
2 - hidden, none visual push. This wont show any visual indicator on any OS!
In Android this will trigger the push(String) call with the message body. In iOS this
will only happen if the application is in the foreground otherwise the push will be lost
3 - 1 + 2 = 3 allows combining a visual push with a non-visual portion. Expects
a message in the form: This is what the user will see;This is
something he wont see . E.g. you can bundle a special ID or even a JSON
string in the hidden part while including a friendly message in the visual part.
When active this will trigger the push(String) method twice, once with the visual and
once with the hidden data.
4 - Allows splitting a visual push request based on the format title;body to
provide better visual representation in some OSs.
723

Appendix: Working With iOS

100 - Applicable only to iOS. Allows setting the numeric badge on the icon to the
given number. The body of the message must be a number e.g. unread count.
101 - identical to 100 with an added message payload separated with a space.
E.g. 30 You have 30 unread messages will set the badge to "30" and present
the push notification text of "You have 30 unread messages".

Badging on iOS
The badge number can be set thru code as well, this is useful if you want the
badge to represent the unread count within your application.
7

To do this we have two methods in the Display

class:
isBadgingSupported() & setBadgeNumber(int) . Notice that even if
isBadgingSupported will return true , it will not work unless you activate
push support!
To truly utilize this you might need to disable the clearing of the badges on startup
which you can do with the build hint ios.enableBadgeClear=false .

16.4.iOS Beta Testing (Testflight)

Apple provides the ability to distribute beta versions of your application to beta testers
using testflight. This allows you to recruit up to 1000 beta testers without the typical
UDID limits a typical Apple account has.
This is supported for pro users as part of the crash protection feature.

To take advantage of that capability use the build hint ios.testFlight=true and
then submit the app to the store for beta testing. Make sure to use a release build target.

16.5.Accessing Insecure URLs

Due to security exploits Apple blocked some access to insecure URLs which means
that http code that worked before could stop working for you on iOS 9+. This is generally
a good move, you should use https and avoid http as much as possible but thats
sometimes impractical especially when working with an internal or debug environment.
7

https://www.codenameone.com/javadoc/com/codename1/ui/Display.html

724

Appendix: Working With iOS

You can disable the strict URL checks from Apple by using the venerable
ios.plistInject build hint and setting it to:
<key>NSAppTransportSecurity</key><dict><key>NSAllowsArbitraryLoads</
key><true/></dict>

However, it seems that Apple will reject your app if you just include that and dont have
a good reason.

16.6.Using Cocoapods
8

CocoaPods is a dependency manager for Swift and Objective-C Cocoa projects. It

has over eighteen thousand libraries and can help you scale your projects elegantly.
Cocoapods can be used in your Codename One project to include native iOS libraries
without having to go through the hassle of bundling the actual library into your project.
Rather than bundling .h and .a files in your ios/native directory, you can specify which
"pods" your app uses via the ios.pods build hint. (There are other build hints also
if you need more advanced features).
Examples
9

Include the AFNetworking library in your app:

ios.pods=AFNetworking

Include the AFNetworking

10

version 3.0.x library in your app:

ios.pods=AFNetworking ~> 3.0

For full versioning syntax specifying pods see the Podfile spec for the "pod" directive

11

16.6.1.Including Multiple Pods

Multiple pods can be separated by either commas or semi-colons in the value of the
ios.pods build hint. E.g. To include GoogleMaps and AFNetworking, you could:
8
https://cocoapods.org/
9
https://github.com/AFNetworking/AFNetworking
10
https://github.com/AFNetworking/AFNetworking
11
https://guides.cocoapods.org/syntax/podfile.html#pod

725

Appendix: Working With iOS

ios.pods=GoogleMaps,AFNetworking

Or specifying versions:
ios.pods=AFNetworking ~> 3.0,GoogleMaps

16.6.2.Other Pod Related Build Hints

ios.pods.platform : The minimum platform to target. In some cases, Cocoapods
require functionality that is not in older version of iOS. For example, the
GoogleMaps pod requires iOS 7.0 or higher, so you would need to add the
ios.pods.platform=7.0 build hint.
ios.pods.sources : Some pods require that you specify a URL for the source of the
pod spec. This may be optional if the spec is hosted in the central CocoaPods source
( https://github.com/CocoaPods/Specs.git ).

16.6.3.Converting PodFile To Build Hints

Most documentation for Cocoapods "pods" provide instructions on what you need
to add to your Xcode projects PodFile. Here is an example from the GoogleMaps
cocoapod to show you how a PodFile can be converted into equivalent build hints in
a Codename One project.
The GoogleMaps cocoapod directs you to add the following to your PodFile:
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '7.0'
pod 'GoogleMaps'

This would translate to the following build hints in your Codename One project:
ios.pods.sources=https://github.com/CocoaPods/Specs.git
ios.pods.platform=7.0
ios.pods=GoogleMaps

(Note that the ios.pods.sources directive is optional).

726

Chapter17.Appendix: Working With

Javascript
This section covers the Codename One Javascript port, which allows you to compile
your app as native javascript and run it inside a browser. This is different from
1
the BrowserComponent and other methods of displaying HTML/Javascript inside a
Codename One app.

17.1.Limitations of the Javascript Port

17.1.1.No Multithreaded Code inside Static Initializers
2

Codename Ones Javascript port uses TeaVM to compile your application directly
to Javascript so that it can run inside modern web browsers without the need for
any plugins (i.e. NOT as an applet). One of the revolutionary features that TeaVM
provides is the ability to run multi-threaded code (i.e. it has full support for Object.wait(),
Object.notify(), Object.notifyAll(), and the synchronized keyword). The one caveat
to be aware of is that you cannot use any threading primitives inside static
initializers. This is due to technical limitations in the browser environment and the way
that TeaVM compiles class definitions into Javascript. The workaround for this issue is
to do lazy initialization in cases where you need to use multithreaded code.
Example
The following code will result in a build error when deploying a Javascript build:
Class1.java
import com.codename1.io.Log;
class Class1 {

public static int getValue() {

Log.p("Hello world");

}
1
2

return 1;

https://www.codenameone.com/javadoc/com/codename1/ui/BrowserComponent.html
http://teavm.org/

727

Appendix: Working With Javascript

Class2.java
class Class2 {

public static int value = Class1.getValue();

This fails because Class2 calls Class1.getValue() in its static initializer, and
getValue() calls Log.p() , which, underneath the covers, writes to Storage which involves some synchronous network access in the Javascript port (i.e. it uses
wait() and notify() under the hood.
If we simply remove the call to Log.p() from getValue() , as follows:
public static int getValue() {
}

return 1;

Then everything would be fine.

But How do we Know if A method includes wait() / notify somewhere along
the line?
When you try to build your app as a Javascript app, it will fail (if code in your static
initializers uses wait() / notify() somewhere along the line).
How to Work Around this Issue
Use lazy initialization wherever you can. You dont need to worry about this for setting
static variables to literal values. E.g.: static int someVal = 20; will always be
fine. But static int someVal = OtherClass.calculateSomeVal(); may
or may not be fine, because you dont know whether calculateSomeVal() uses
a wait/notify . So instead of initializing someVal in the static initializer, create a
static accessor that lazily initializes it. Or initialize it inside your apps init() method.
Or initialize it inside the class constructor.

17.2.Troubleshooting Build Errors

If your Javascript build fails, you should download the error log and see what the
problem is. The most common errors are:
728

Appendix: Working With Javascript

1. "[ERROR] Method XXX.<clinit>()V is claimed to be synchronous, but it is has
invocations of asynchronous methods"
This error will occur if you have static initializers that use multithreaded code (e.g.
wait/notify/sleep, etc). See Static Initializers for information about troubleshooting
this error. In some cases TeaVM may give a false-positive here (i.e. it thinks you are
doing some multithreaded stuff, but youre really not), then you can force the build
to "succeed" by adding the javascript.stopOnErrors=false build hint.
2. "Method XXX was not found"
TeaVM uses its own Java runtime library. It is mostly complete, but you may
occasionally run into methods that havent been implemented. If you run into errors
saying that certain classes or methods were not found, please post them to the
3
Codename One issue tracker . You can also work around these by changing your
own code to not use such functions. If this missing method doesnt fall on a critical
path on your app, you can also force the app to still build despite this error by adding
the javascript.stopOnErrors=false build hint.

17.3.ZIP, WAR, or Preview. Whats the difference?

The Javascript build target will result in up to three different bundles being generated:
1. YourApp-1.0.war
2. YourApp-1.0.zip
3. YourApp-1.0-Preview.html
YourApp-1.0.war is a self contained application bundle that can be installed in any
JavaEE servlet container. If you havent customized any proxy settings, then the
application will be configured to use a proxy servlet that is embedded into the .war file.
As an example, the PropertyCross .war file contains the following files:
$ jar tvf PropertyCross-1.0.war
0 Thu Apr 30 15:57:38 PDT 2015
132 Thu Apr 30 15:57:36 PDT 2015
0 Thu Apr 30 15:57:36 PDT 2015
0 Thu Apr 30 15:57:36 PDT 2015
0 Thu Apr 30 15:57:36 PDT 2015
3

META-INF/
META-INF/MANIFEST.MF
assets/
assets/META-INF/
js/

https://github.com/codenameone/CodenameOne/issues

729

Appendix: Working With Javascript

0 Thu Apr 30 15:57:36 PDT 2015 teavm/

0 Thu Apr 30 15:57:36 PDT 2015 WEB-INF/

0 Thu Apr 30 15:57:36 PDT 2015 WEB-INF/classes/
0 Thu Apr 30 15:57:36 PDT 2015 WEB-INF/classes/com/

0 Thu
0 Thu
corsproxy/
0 Thu
27568 Thu
306312 Thu
427737 Thu
350 Thu
92671 Thu
23549 Thu
2976 Thu
30695 Thu
84319 Thu

Apr 30 15:57:36 PDT 2015 WEB-INF/classes/com/codename1/

Apr 30 15:57:36 PDT 2015 WEB-INF/classes/com/codename1/
Apr
Apr
Apr
Apr
Apr
Apr
Apr
Apr
Apr
Apr

30
30
30
30
30
30
30
30
30
30

15:57:36
15:57:12
15:57:12
15:57:12
15:57:12
15:57:12
15:57:14
15:57:14
15:57:12
15:57:12

PDT
PDT
PDT
PDT
PDT
PDT
PDT
PDT
PDT
PDT

2015
2015
2015
2015
2015
2015
2015
2015
2015
2015

WEB-INF/lib/
assets/CN1Resource.res
assets/iOS7Theme.res
assets/iPhoneTheme.res
assets/META-INF/MANIFEST.MF
assets/theme.res
icon.png
index.html
js/fontmetrics.js
js/jquery.min.js

13261 Thu Apr 30 15:57:12 PDT 2015 progress.gif

2816 Thu Apr 30 15:57:12 PDT 2015 style.css
1886163 Thu Apr 30 15:57:36 PDT 2015 teavm/classes.js
359150 Thu Apr 30 15:57:36 PDT 2015 teavm/classes.js.map
1147502 Thu Apr 30 15:57:36 PDT 2015 teavm/classes.js.teavmdbg
30325 Thu Apr 30 15:57:36 PDT 2015 teavm/runtime.js
1011 Thu Apr 30 15:57:18 PDT 2015 WEB-INF/classes/com/codename1/
corsproxy/CORSProxy.class
232771 Wed Nov 05 17:35:12 PST 2014 WEB-INF/lib/commons-codec-1.6.jar
62050 Wed Apr 15 14:35:56 PDT 2015 WEB-INF/lib/commons-logging-1.1.3.jar
590004 Wed Apr 15 14:35:58 PDT 2015 WEB-INF/lib/httpclient-4.3.4.jar
282269 Wed Apr 15 14:35:56 PDT 2015 WEB-INF/lib/httpcore-4.3.2.jar
14527 Wed Apr 15 14:35:56 PDT 2015 WEB-INF/lib/smiley-http-proxyservlet-1.6.jar
903 Thu Apr 30 15:57:12 PDT 2015 WEB-INF/web.xml
9458 Thu Apr 30 15:57:14 PDT 2015 META-INF/maven/com.propertycross/
PropertyCross/pom.xml
113 Thu Apr 30 15:57:36 PDT 2015 META-INF/maven/com.propertycross/
PropertyCross/pom.properties

Some things to note in this file listing:

1. The index.html file is the entry point to the application.
2. CORSProxy.class is the proxy servlet for making network requests to other
domains.
3. The assets directory contains all of your applications jar resources. All resource
files in your app will end up in this directory.
730

Appendix: Working With Javascript

4. The teavm directory contains all of the generated javascript for your application.
Notice that there are some debugging files generated (classes.js.map and
classes.js.teavmdbg). These are not normally loaded by the browser when your
app is run, but they can be used by Chrome when you are doing debugging.
5. The jar files in the WEB-INF/lib directory are dependencies of the proxy servlet.
They are not required for your app to run - unless you are using the proxy.
YourApp-1.0.zip is appropriate for deploying the application on any web server. It
contains all of the same files as the .war file, excluding the WEB-INF directory (i.e. it
doesnt include any servlets, class files, or Java libraries - it contains purely client-side
javascript files and HTML).
As an example, this is a listing of the files in the zip distribution of the PropertyCross
demo:
$ unzip -vl PropertyCross-1.0.zip
Archive: /path/to/PropertyCross-1.0.zip
Length
Method
Size Ratio
Date
-------- ------ ------- -------27568 Defl:N
26583
4% 04-30-15
CN1Resource.res
306312 Defl:N
125797 59% 04-30-15
iOS7Theme.res
427737 Defl:N
218975 49% 04-30-15
iPhoneTheme.res
350 Defl:N
241 31% 04-30-15
MANIFEST.MF
92671 Defl:N
91829
1% 04-30-15
23549 Defl:N
23452
0% 04-30-15
2903 Defl:N
1149 60% 04-30-15
30695 Defl:N
7937 74% 04-30-15
fontmetrics.js
84319 Defl:N
29541 65% 04-30-15
13261 Defl:N
11944 10% 04-30-15
2816 Defl:N
653 77% 04-30-15
1886163 Defl:N
315437 83% 04-30-15
359150 Defl:N
92874 74% 04-30-15
classes.js.map
1147502 Defl:N
470472 59% 04-30-15
classes.js.teavmdbg
30325 Defl:N
5859 81% 04-30-15
-------------- --4435321
1422743 68%

731

Time
---15:57

CRC-32
-----9dc91739

Name
---assets/

15:57

0b5c1c3a

assets/

15:57

3de499c8

assets/

15:57

7e7e3714

assets/META-INF/

15:57
15:57
15:57
15:57

004ad9d7
acd79066
e5341de1
2e008f6c

assets/theme.res
icon.png
index.html
js/

15:57
15:57
15:57
15:57
15:57

15b91689
51b895c7
a12159c7
2b34c50f
30abdf13

js/jquery.min.js
progress.gif
style.css
teavm/classes.js
teavm/

15:57

e5c456f7

teavm/

15:57

46651f06

teavm/runtime.js
------15 files

Appendix: Working With Javascript

Youll notice that it has many of the same files as the .war distribution. It is just missing
the the proxy servlet and dependencies.
YourApp-1.0-Preview.html is a single-page HTML file with all of the applications
resources embedded into a single page. This is generated for convenience so that you
can preview your application on the build server directly. While you could use this file
in production, you are probably better to use the ZIP or WAR distribution instead as
some mobile devices have file size limitations that may cause problems for the "one
large single file" approach. If you do decide to use this file for your production app (i.e.
copy the file to your own web server), you will need to change the proxy settings, as
it is configured to use the proxy on the Codename One build server - which wont be
available when the app is hosted on a different server.

17.4.Setting up a Proxy for Network Requests

4

The Codename One API includes a network layer (the NetworkManager and
5
ConnectionRequest classes) that allows you to make HTTP requests to arbitrary
destinations. When an application is running inside a browser as a Javascript app, it
is constrained by the same origin policy. You can only make network requests to the
same host that served the app originally.
E.g. If your application is hosted at http://example.com/myapp/index.html, then your
app will be able to perform network requests to retrieve other resources under the
example.com domain, but it wont be able to retrieve resources from example2.com,
foo.net, etc..
The HTTP standard does support cross-origin requests in
the browser via the Access-Control-Allow-Origin HTTP
header. Some web services supply this header when serving
resources, but not all. The only way to be make network requests to
arbitrary resources is to do it through a proxy.
Luckily there is a solution. The .war javascript distribution includes an embedded proxy
servlet, and your application is configured, by default, to use this servlet. If you intend to
use the .war distribution, then it should just work. You shouldnt need to do anything
to configure the proxy.

4
5

https://www.codenameone.com/javadoc/com/codename1/io/NetworkManager.html
https://www.codenameone.com/javadoc/com/codename1/io/ConnectionRequest.html

732

Appendix: Working With Javascript

If, however, you are using the .zip distribution or the single-file preview, you will need to
set up a Proxy servlet and configure your application to use it for its network requests.

17.4.1.Step 1: Setting up a Proxy

This section is only relevant if you are using the .zip or single-file
distributions of your app. You shouldnt need to set up a proxy for
the .war distribution since it includes a proxy built-in.
6

The easiest way to set up a proxy is to use the Codename One cors-proxy project.
This is the open-source project from which the proxy in the .war distribution is derived.
Simply download and install the cors-proxy .war file in your JavaEE compatible servlet
container.
If you dont want to install the .war file, but would rather just copy the proxy servlet
into an existing web project, you can do that also. See the cors-proxy wiki for more
7
information about this .

17.4.2.Step 2: Configuring your Application to use the Proxy

There are three ways to configure your application to use your proxy.
1. Using the javascript.proxy.url build hint.
E.g.:
javascript.proxy.url=http://example.com/myapp/cn1-cors-proxy?_target=

2. By modifying your apps index.html file after the build.

E.g.:
<script type="text/javascript">
window.cn1CORSProxyURL='http://example.com/myapp/cn1-cors-proxy?
_target=';
</script>

3. By setting the javascript.proxy.url property in your Java source. Generally

you would do this inside your init() method, but it just has to be executed before
you make a network request that requires the proxy.
6
7

https://github.com/shannah/cors-proxy
https://github.com/shannah/cors-proxy/wiki/Embedding-Servlet-into-Existing-Project

733

Appendix: Working With Javascript

Display.getInstance().setProperty(
"javascript.proxy.url",
"http://example.com/myapp/cn1-cors-proxy?_target="
);

The method you choose will depend on the workflow that you prefer. Options #1 and
#3 will almost always result in fewer changes than #2 because you only have to set
them up once, and the builds will retain the settings each time you build your project.

17.5.Customizing the Splash Screen

Since your application may include many resource files, videos, etc.., the the buildserver will generate a splash screen for your app to display while it is loading. This
basically shows a progress indicator with your apps icon.
You can customize this splash screen by simply modifying the HTML source inside the
cn1-splash div tag of your apps index.html file:
<div id="cn1-splash">
<img class="icon" src="icon.png"/>
<img class="progress" src="progress.gif"/>
<p>...Loading...</p>
</div>

17.6.Debugging
If you run into problems with your app that only occur in the Javascript version, you may
need to do a little bit of debugging. There are many debugging tools for Javascript, but
the preferred tool for debugging Codename One apps is Chromes debugger.
If your application crashes and you dont have a clue where to begin, follow these steps:
1. Load your application in Chrome.
2. Open the Chrome debugger.
3. Enable the "Pause on Exceptions" feature, then click the "Refresh" button to reload
your app.
4. Step through each exception until you reach the one you are interested in. Chrome
will then show you a stack trace that includes the name of the Java source file and
line numbers.

734

Appendix: Working With Javascript

Figure 17.1. Debugging using Chrome tools

17.7.Including Third-Party Javascript Libraries

Codename One allows you to interact directly with Javascript using native interfaces.
Native interfaces are placed inside your projects native/javascript directory
using a prescribed naming convention. If you want to, additionally, include third-party
Javascript libraries in your application you should also place these libraries inside the
native/javascript directory but you must specify which files should be treated

735

Appendix: Working With Javascript

as "libraries" and which files are treated as "resources". You can do this by adding a
file with extension .cn1mf.json file either the root of your native/javascript
directory or the root level of the projects src directory.

17.7.1.Libraries vs Resources
A resource is a file whose contents can be loaded by your application at runtime
using Display.getInstance().getResourceAsStream() . In a typical Java
environment, resources would be stored on the applications classpath (usually
inside a Jar file). On iOS, resources are packaged inside the application bundle. In
the Javascript port, resources are stored inside the APP_ROOT/assets directory.
Historically, javascript files have always been treated as resources in Codename
One, and many apps include HTML and Javascript files for use inside the
8
BrowserComponent .
With the Javascript port, it isnt quite so clear whether a Javascript file is meant to be
a resource or a library that the application itself uses. Most of the time you probably
want Javascript files to be used as libraries, but you might also have Javascript files
in your app that are meant to be loaded at runtime and displayed inside a Web View
- these would be considered resources.

17.7.2.The Javascript Manifest File

In order to differentiate libraries from resources, you should provide a cn1mf.json file
inside your native/javascript directory that specifies any files or directories that
should be treated as libraries. This file can be named anything you like, as long as
its name ends with cn1mf.json . Any files or directories that you list in this manifest
file will be packaged inside your apps includes directory instead of the assets
directory. Additionally it add appropriate <script> tags to include your libraries as
part of the index.html page of your app.
If you include the cn1mf.json file in your projects src
directory it could potentially be used to add configuration parameters
to platforms other than Javascript (although currently no other
platforms use this feature). If you place it inside your native/
javascript directory, then only the Javascript port will use the
configuration contained therein.
A simple manifest file might contain the following JSON:
8

https://www.codenameone.com/javadoc/com/codename1/ui/BrowserComponent.html

736

Appendix: Working With Javascript

"javascript" : {
"libs" : [

"mylib1.js"

I.e. It contains a object with key libs whose value is a list of files that should be treated as
libraries. In the above example, we are declaring that the file native/javascript/
mylib1.js should be treated as a library. This will result in the following <script>
tag being added to the index.html file:
<script src="includes/mylib1.js"></script>

This also caused the mylib1.js file to be packaged inside the

includes directory instead of the assets directory.
A project may contain more than one manifest file. This allows you to
include manifest files with your cn1libs also. You just need to make
sure that each manifest file has a different name.

How to NOT generate the <script> tag

In some cases you may want a Javascript file to be treated as a library (i.e. packaged
in the includes directory) but not automatically included in the index.html page.
Rather than simply specifying the name of the file in the libs list, you can provide a
structure with multiple options about the file. E.g.
{

"javascript" : {
"libs" : [
"mylib1.js",
{
"file" : "mylib2.js",
"include" : false
}
]
}

737

Appendix: Working With Javascript

In the above example, the mylib2.js file will be packaged inside the includes
directory, but the build server wont insert its <script> tag in the index.html
page.

Library Directories
You can also specify directories in the manifest file. In this case, the entire directory will
be packaged inside the includes directory of your app.
If you are including Javascript files in your app that are contained
inside a directory hierarchy, you should specify the root directory of
the hierarchy in your manifest file and use the sub "includes" property
of the directory entry to specify which files should be included with
<script> tags. Specifying the file directly inside the "libs" list will
result in the file being packed directly in the your apps includes
directory. This may or may not be what you want.
E.g.
{

"javascript" : {
"libs" : [
"mylib1.js",
{
"file" : "mylib2.js",
"include" : false
},
{
"file" : "mydir1",
"includes" : ["subfile1.js", "subfile2.js"]
}
}

In this example the entire mydir1 directory would be packed inside the apps
includes directory, and the following script tags would be inserted into the
index.html file:
<script src="includes/mydir1/subfile1.js"></script>
<script src="includes/mydir1/subfile2.js"></script>

738

Appendix: Working With Javascript

Libraries included from a directory hierarchy may not work correctly
with the single file preview that the build server generates. For that
version, it will embed the contents of each included Javascript file
inside the index.html file, but the rest of the directory contents
will be omitted. If your the library depends on the directory hierarchy
and supporting files and you require the single-file preview to work,
then you may consider hosting the library on a separate server, and
including the library directly from there, rather than embedding it
inside your projects "native/javascript" directory.

Including Remote Libraries

The examples so far have only demonstrated the inclusion of libraries that are part of
the app bundle. However, you can also include libraries over the network by specifying
the URL to the library directly. This is handy for including common libraries that are
hosted by a CDN.
E.g. The Google Maps library requires the Google maps API to be included. This is
accomplished with the following manifest file contents:
{

"javascript" : {
"libs" : [
"//maps.googleapis.com/maps/api/js?v=3.exp"
]
}

This example uses the "//" prefix for the URL instead of specifying
the protocol directly. This allow the library to work for both http and
https hosting. You could however specify the protocol as well:
+
{

"javascript" : {
"libs" : [
"https://maps.googleapis.com/maps/api/js?v=3.exp"
]
}

739

Appendix: Working With Javascript

Including CSS Files

CSS files can be included using the same mechanism as is used for Javascript files. If
the file name ends with ".css", then it will be treated as a CSS file (and included with
a <link> tag instead of a <script> tag. E.g.
{

"javascript" : {
"libs" : [
"mystyles.css"
]
}

or
{

"javascript" : {
"libs" : [
"https://example.com/mystyles.css"
]
}

Embedding Variables in URLs

In some cases the URL for a library may depend on the values of some build hints in
the project. For example, in the Google Maps cn1lib, the API key must be appended to
the URL for the API as a GET parameter. E.g. https://maps.googleapis.com/
maps/api/js?v=3.exp&key=SOME_API_KEY , but the developer of the library
doesnt want to put his own API key in the manifest file for the library. It would be better
for the API key to be supplied by the developer of the actual app that uses the library
and not the library itself.
The solution for this is to add a variable into the URL as follows:
{

"javascript" : {
"libs" : [
"//maps.googleapis.com/maps/api/js?
v=3.exp&key={{javascript.googlemaps.key}}"

740

Appendix: Working With Javascript

The {{javascript.googlemaps.key}} variable will be replaced with the value

of the javascript.googlemaps.key build hint by the build server, so the resulting
include you see in the index.html page will be something like:
<script src="//maps.googleapis.com/maps/api/js?v=3.exp&key=XYZ"></script>

17.8.Browser Environment Variables

Native interfaces allow you to interact with the Javascript environment
in unlimited ways, but Codename One provides a simpler method of
obtaining some common environment information from the browser via the
Display.getInstance().getProperty() method. The following environment
variables are currently available:

Table 17.1. Property hints for the JavaScript port

Name

Description

browser.window.location.href

A String, representing the entire URL

of the page, including the protocol (like
http://)

browser.window.location.search A String, representing the querystring

part of a URL, including the question
mark (?)
browser.window.location.host

A String, representing the domain name

and port number, or the IP address of a
URL

browser.window.location.hash

A String, representing the anchor part of

the URL, including the hash sign (#)

browser.window.location.origin A String, representing the protocol

(including ://), the domain name (or IP
address) and port number (including
the colon sign (:) of the URL. For URLs
using the "file:" protocol, the return value
differs between browsers
741

Appendix: Working With Javascript

Name

Description

browser.window.location.pathname
A String, representing the pathname
browser.window.location.protocol
A String, representing the protocol of the
current URL, including the colon (:)
browser.window.location.port

A String, representing the port number of

a URL. + Note: If the port number is not
specified or if it is the schemes default
port (like 80 or 443), an empty string is
returned

browser.window.location.hostname
A String, representing the domain name,
or the IP address of a URL
User-Agent

The User-agent string identifying the

browser, version etc..

browser.language

The language code that the browser is

currently set to. (e.g. en-US)

browser.name

the name of the browser as a string.

Platform

a string that must be an empty string or a

string representing the platform on which
the browser is executing. + For example:
"MacIntel", "Win32", "FreeBSD i386",
"WebTV OS"

browser.codeName

the internal name of the browser

browser.version

the version number of the browser

javascript.deployment.type

Specifies the deployment type of the

app. This will be "file" for the singlefile preview, "directory" for the zip
distribution, and "war" for the war
distribution.

17.9.Changing the Native Theme

Since a web application could potentially be run on any platform, it isnt feasible to
bundle all possible themes into the application (at least it wouldnt be efficient for most
use cases). By default we have bundled the iOS7 theme for javascript applications. This
means that the app will look like iOS7 on all devices: desktop, iOS, Android, WinPhone,
etc
742

Appendix: Working With Javascript

You
can
override
this
behavior
dynamically
by
setting
the
9
javascript.native.theme Display property to a theme that you have included

in your app. All of the native themes are available on GitHub, so you can easily copy
these into your application. The best place to add the theme is in your native/
javascript directory - so that they wont be included for other platforms.

17.9.1.Example: Using Android Theme on Android

10

First, download androidTheme.res from the Android port on GitHub, and copy it into
your apps native/javascript directory.
Then in your apps init() method, add the following:
Display d = Display.getInstance();

if (d.getProperty("User-Agent", "Unknown").indexOf("Android") != -1) {

}

d.setProperty("javascript.native.theme", "/androidTheme.res");

https://www.codenameone.com/javadoc/com/codename1/ui/Display.html
10
https://github.com/codenameone/CodenameOne/raw/master/Ports/Android/src/androidTheme.res

743

Chapter18.Deploying UWP Apps

UWP Apps may distributed in 2 different ways:
1. In the Windows App Store. (This should be used for deployment of any production
app).
2. Outside of the Windows App Store via sideloading directly onto a device. This
should only be used for development.

18.1.Deploying Outside of the Windows App Store

(Sideloading)
UWP apps may be deployed directly to Windows 10 desktop and mobile devices
without any need to involve the Windows Store. This process is only realistic, though,
for testing and debugging your app during development because it requires you
to enable "Development" mode on the device. In addition, installation is a little bit
more complicated than simply downloading an app over the internet. The process for
deploying to Windows 10 desktop devices is different than the process for mobile
devices. These are described in the following sections.

18.1.1.Side-loading to Windows 10 Mobile Devices

Enabling Developer Mode on Device
Before you can side-load apps onto your phone, youll need to set up your phone for
development.
1. In "Settings", select "Update & Security" > "For developers"

744

Deploying UWP Apps

745

Deploying UWP Apps

2. Select "Developer mode"

746

Deploying UWP Apps

3. Under "Device Discovery", make sure that the "Make your device visible to USB
connections and your local network" is set to "On".

747

Deploying UWP Apps

4. Make sure that "Device Portal" is set to "On"

748

Deploying UWP Apps

5. When you switch "Device Portal" to "On" it should show you an address that you
can access the Phone at via wifi. (E.g. https://10.0.1.11). Remember this address,
youre going to use it to install all of your apps onto the device.
This will be a local address within your local network. It wont be
available to the outside world.
At this point, your phone should be ready to receive "Side-loaded" apps. This was a
one-time setup, so you shouldnt have to do it again, until you set up another device.

Building App for UWP

Now that your device is set up for development, you can proceed to build your app.
1. Select the "Mobile Debug Build" option in the UWP Codename One Settings.

2. Select the "Send Windows UWP Build" option in the Codename One menu of your
IDE. This will initiate the build on the Codename One build server.

749

Deploying UWP Apps

3. Log into the Codename One dashboard to watch the build progress. When it is
complete, youll be able to download the ".appxbundle" file to your desktop.

You cannot simply download the .appxbundle file directly to your

Windows Phone 10 mobile device and install it. It will indeed
allow you to download it, and will give you an option to install it,
but the install will silently fail.

750

Deploying UWP Apps

Installing App On Device

1. Point your computers web browser to the address for your mobile device. (This
is the address listed when you turned on the "Device Portal" in the "Enabling
Developer Mode on Device" section above. This will open the App Manager page.
2. Click on the "Apps" item in the left menu.

3. If this is the first time installing a UWP (debug) app on your device, you will need
to install the dependencies. You can find the dependencies for mobile/ARM apps
1
here . Youll need to install both Microsoft.NET.CoreRuntime.1.0.appx
and Microsoft.VCLibs.ARM.Debug.14.00.appx . If this is not the first
time installing a UWP app, you can skip to the next step.
a. Under the "Install App" section, click the "Choose File" button and navigate
through the file chooser to select the "Microsoft.NET.CoreRuntime.1.0.appx"
file. Then click "Go".
1

https://github.com/codenameone/cn1-binaries/tree/master/uwp/Dependencies/ARM

751

Deploying UWP Apps

b. Do the same for the "Microsoft.VCLibs.ARM.Debug.14.00.appx" file.
4. Under the "Install App" section, click the "Choose File" button and navigate through
the file chooser to select the .appxbundle file for your app.
5. Once you have the appxbundle selected, you should press "Go" under the "Deploy"
subheading. This will install the app and, if all went well, your app will appear in the
"Recently Added" section in the apps list of the phone.

752

Deploying UWP Apps

753

Deploying UWP Apps

18.1.2.Side-loading to Windows 10 Desktop Devices

Enabling Developer Mode on PC
The easiest way to be able to run your development apps on a Windows 10 PC is to
enable developer mode. This will allow you to install any app even if it is just "selfsigned".
To enable developer mode, open "Settings", then select "Updates an Security". Under
the "For Developers" menu item, select "Developer Mode" as shown below:

Building the App

Before building the app, youll need to ensure that the build target is set to "Debug
Desktop" in the Codename One Settings panel for Windows apps.
Steps:
1. Open Codename One Settings (steps vary by IDE). On Netbeans you will find
"Codename One Settings" by right clicking your projects node in the project
explorer, and look in the "Codename One" submenu:

754

Deploying UWP Apps

2. Click on "Windows Settings":

3. Under "Build Type", make sure that "Desktop Debug Build" is selected, as shown
below:

755

Deploying UWP Apps

4. Save the changes by clicking the "Disk" icon in the upper right:

Now you can proceed to send the build to the build server.
1. Select the "Send Windows UWP Build" option in the Codename One menu of your
IDE. This will initiate the build on the Codename One build server.

756

Deploying UWP Apps

2. Log into the Codename One dashboard to watch the build progress. When it is
complete, youll be able to download the ".zip" file to the Windows 10 PC on which
you wish to install the app.

Installing the App

Start by extracting the .zip file. (Navigate to the folder where the zip was downloaded,
right click it, and select "Extract all" as shown below:

757

Deploying UWP Apps

After extraction, open the resulting directory. You should see contents similar to the
following:

Downloading Dependencies
If this is your first time installing a UWP app on this PC, you may need to add the
2
dependencies before you can install. You can download the dependencies here .
Extract "Dependencies.zip" and copy the resulting "Dependencies" directory into the
app install directory. Your app install directory should now look like:
2

https://github.com/codenameone/cn1-binaries/raw/master/uwp/Dependencies.zip

758

Deploying UWP Apps

Running the Powershell Script

We are finally at the point where we can run the installer.
Right-click on the "Add-AppDevPackage" icon, and select "Run in Powershell", as
shown:

You may be prompted that you need to change the execution policy, in Powershell:

Enter "Y" at the prompt to allow this.

If all goes well, you should see a message saying that the app as successfully installed.
759

Deploying UWP Apps

And if you look in your "Windows Menu" under "All Apps", you should see your app
listed there:

760

Deploying UWP Apps

18.1.3.Building for the Windows Store

If you want to be able to distribute your app to the public, the Windows Store is your
best channel. Building for the Windows store involves roughly 3 steps:

761

Deploying UWP Apps

1. Reserve a name for your app in the Windows Store
2. Build your app using the "Windows Store Upload" build type.
3. Upload the resulting .appxupload file to the Windows store.
3

Lets go through these steps in more detail. Start here .

If you dont already have an account, sign up for one. Then log in. Once logged in, you
can click the "Dashboard" link on the toolbar.

https://developer.microsoft.com/en-us/windows/publish

762

Deploying UWP Apps

Under the "Your apps" section (on the left in the above screenshot), click the "Create
new app" button.

763

Deploying UWP Apps

Enter a name for your app, and click "Reserve app name".
If the name was available, it should take you to the app overview page for your new
app. Theres quite a few options there to play with, but were not going to worry about
any of them for now. All we need to know is:
1. Your Apps ID
2. Your Apps Publisher ID
You can get this information by scrolling down to the bottom of the "App overview"
page and clicking the "View app identity details" under the "App Management" > "App
identity" section:

Youll see a page with the information we need shown below:

764

Deploying UWP Apps

The next step is to copy this information into your Codename One project.
Open up the Codename One Settings for your project and go to the "Windows Settings"
section.
Copy and paste the "Package/Identity/Name" and "Package/Properties/
PublisherDisplayName" values from the windows store into the "App ID" and "Publisher
Display Name" fields respectively.
It is important that your App ID and Publisher Display Name match
exactly what you have in the store, or your app will fail at the
validation stage when you try to upload your app to the store.
Next, click on the "Generate" button next to the Certificate field.
This will open a dialog titled "Certificate Generator". Paste the value from the "Package/
Identity/Publisher" listed in the Windows Store into the Publisher ID field as shown
below:

Then click OK. This will generate a .pfx file inside your project folder.
The "Display Name" must also match that app name in the store.
Finally, make sure that "Windows Store Upload" is selected in the "Build Type" field.
For the example above, my settings form looks like the following screenshot when I
am done.

765

Deploying UWP Apps

When you are done, hit the "Save" icon in the upper right corner of the window to save
your changes.
Finally, select "Codename One" > "Send Windows UWP Build" in your IDEs project
explorer.
This will produce an .appxupload file that you can upload to the Windows Store.
4

See the Microsofts documentation on uploading app packages for more information
on the remaining steps.

18.2.Debugging UWP Apps

On most platforms, there is a device log that records errors, exceptions, and messages
written to STDOUT. UWP, unfortunately, doesnt seem to provide this. If you are running
on Windows Phone 10, there doesnt seem to be any device log at all. There is a
separate program called "Field Medic" that you can use to do some logging, but it
doesnt capture application errors or STDOUT messages.
The best way to debug apps on device is to enable crash protection in your app. This
can be enabled by adding the following to your apps init() method:
Log.bindCrashProtection(true);

With crash protection enabled, youll receive an email whenever an exception is

thrown that isnt caught in your application code. The email will include the stack
trace of the error along with any output you had previously provided using the
com.codename1.io.Log class (e.g. Log.p() and Log.e() ).
A Pro account (or higher) is required to receive crash protection
emails.

18.2.1.No Line Numbers in Stack Traces

One major annoyance of UWP is that it doesnt provide line numbers in its stack traces.
Here is what you can expect to see in a stack trace:
[EDT] 0:0:7,683 - Results null
[EDT] 0:0:7,799 - Exception: java.lang.NullPointerException - null
4

https://msdn.microsoft.com/en-us/windows/uwp/publish/upload-app-packages

766

Deploying UWP Apps

at com.codename1.ui.Display.invokeAndBlock(Runnable r, Boolean

dropEvents)[EDT] 0:0:7,815 - Exception in AppName version 1.1

[EDT] 0:0:7,830 - OS win
[EDT] 0:0:7,836 - Error java.lang.NullPointerException

[EDT] 0:0:7,836 - Current Form null

[EDT] 0:0:7,836 - Exception: java.lang.NullPointerException - null
at System.Environment.GetStackTrace(Exception e, Boolean needFileInfo)
at System.Environment.get_StackTrace()
at UWPApp.IKVMReflectionHelper.getCurrentStackTrace()
at java.lang.ThrowableHelper.getCurrentStackTrace()
at java.lang.Throwable..ctor()
at java.lang.Exception..ctor()
at java.lang.RuntimeException..ctor()
at java.lang.NullPointerException..ctor()
at java.lang.Throwable.__mapImpl(Exception )
at IKVM.Internal.ExceptionHelper.MapException[T](Exception x, Boolean
remap, Boolean unused)
at IKVM.Runtime.ByteCodeHelper.MapException[T](Exception x, MapFlags
mode)
at com.codename1.ui.Display.invokeAndBlock(Runnable r, Boolean
dropEvents)
at com.codename1.ui.Display.invokeAndBlock(Runnable r)
at com.codename1.impl.SilverlightImplementation.editString(Component
n1, Int32 n2, Int32 n3, String n4, Int32 n5)
at
com.codename1.impl.CodenameOneImplementation.editStringImpl(Component
cmp, Int32 maxSize, Int32 constraint, String text, Int32
initiatingKeycode)
at com.codename1.ui.Display.editString(Component cmp, Int32 maxSize,
Int32 constraint, String text, Int32 initiatingKeycode)
at com.codename1.ui.Display.editString(Component cmp, Int32 maxSize,
Int32 constraint, String text)
at com.codename1.ui.TextArea.editString()
at com.codename1.ui.TextArea.pointerReleased(Int32 x, Int32 y)
at com.codename1.ui.TextField.pointerReleased(Int32 x, Int32 y)
at com.codename1.ui.Form.pointerReleased(Int32 x, Int32 y)
at com.codename1.ui.Component.pointerReleased(Int32[] x, Int32[] y)
at com.codename1.ui.Display.handleEvent(Int32 offset)
at com.codename1.ui.Display.edtLoopImpl()
at com.codename1.ui.Display.mainEDTLoop()
at com.codename1.ui.RunnableWrapper.run()
at com.codename1.impl.CodenameOneThread.run()
at java.lang.Thread.threadProc2()
at java.lang.Thread.threadProc()
at java.lang.Thread.1.Invoke()

767

Deploying UWP Apps

at

com.codename1.impl.NativeThreadImpl.<>c__DisplayClass6_0.<init>b__0()
at System.Threading.Tasks.Task.InnerInvoke()
at System.Threading.Tasks.Task.Execute()

at System.Threading.Tasks.Task.ExecutionContextCallback(Object obj)
at System.Threading.ExecutionContext.Run(ExecutionContext
executionContext, ContextCallback callback, Object state)
at System.Threading.Tasks.Task.ExecuteWithThreadLocal(Task&
currentTaskSlot)
at System.Threading.Tasks.Task.ExecuteEntry(Boolean
bPreventDoubleExecution)
at
System.Threading.Tasks.ThreadPoolTaskScheduler.LongRunningThreadWork(Object
obj)
at System.Threading.ThreadHelper.ThreadStart_Context(Object state)
at System.Threading.ExecutionContext.Run(ExecutionContext
executionContext, ContextCallback callback, Object state)

at System.Threading.ThreadHelper.ThreadStart(Object obj)
Originating from:
Message=Object reference not set to an instance of an object.
at com.propertycross.codename1.PropertyCross.1.run()
at com.codename1.ui.Display.processSerialCalls()
at com.codename1.ui.Display.edtLoopImpl()
at com.codename1.ui.Display.invokeAndBlock(Runnable r, Boolean
dropEvents)

It will show you the call stack with the names of the methods. But it wont show you
the line numbers. If the stack trace isnt specific enough, you can add Log.p()
statements in various positions in my code to help narrow down the source of the
exception.

768

Chapter19.Appendix: Casual Game

Programming
While game developers have traditionally used C/OpenGL to get every bit of
performance out of a device, Java offers a unique opportunity for casual game
developers. In this section we will build a simple card game in Java that can run
unchanged on iOS, Android etc.
Casual games are often the most influential games of all, they cross demographics
such as the ubiquitous solitaire or even the chart topping Angry birds. Putting them in
the same game category as 3D FPS games doesnt always make sense.
Yes, framerates are important but ubiquity, social connectivity & gameplay are even
more important for this sub genre of the game industry. The mobile aspect highlights
this point further, the way app stores are built releasing often puts your game at an
advantage over its competitors. Yet releasing to all platforms and all screen sizes
becomes an issue soon enough.
Typically a game is comprised of a game loop which updates UI status based on game
time and renders the UI. However, with casual games constantly rendering is redundant
and with mobile games it could put a major drain on the battery life. Instead we will use
components to build the game elements and let Codename One do the rendering for us.

19.1.The Game
We will create a poker game for 1 player that doesnt include the betting process or any
of the complexities such as AI, card evaluation or validation. This allows us to fit the
whole source code in 270 lines of code (more due to comments). I also chose to simplify
the UI for touch devices only, technically it would be pretty easy to add keypad support
but it would complicate the code and require additional designs (for focus states).
You can see the game running on the simulator at http://
www.youtube.com/watch?v=4IQGBT3VsSQ
The game consists of two forms: Splash screen and the main game UI.

769

Appendix: Casual Game Programming

19.1.1.Handling Multiple Device Resolutions

In mobile device programming every pixel is crucial because of the small size of the
screen, however we cant shrink down our graphics too much because it needs to be
"finger friendly" (big enough for a finger) and readable. There is great disparity in the
device world, even within the iOS family the retina iPad has more than twice the screen
density of the iPad mini. This means that an image that looks good on the iPad mini will
seem either small or very pixelated on an iPad, on the other hand an image that looks
good on the iPad would look huge (and take up too much RAM) on the iPad mini. The
situation is even worse when dealing with phones and Android devices.
Thankfully there are solutions, such as using multiple images for every density (DPI).
However, this is tedious for developers who need to scale the image and copy it every
time for every resolution. Codename One has a feature called MultiImage which
implicitly scales the images to all the resolutions on the desktop and places them within
the res file, in runtime you will get the image that matches your devices density.
There is a catch though MultiImage is designed for applications where we want
the density to determine the size. So an iPad will have the same density as an iPhone
since both share the same amount of pixels per inch. This makes sense for an app
since the images will be big enough to touch and clear. Furthermore, since the iPad
screen is larger more data will fit on the screen!
However, game developers have a different constraint when it comes to game
elements. In the case of a game we want the images to match the device resolution
and take up as much screen real estate as possible, otherwise our game would be
constrained to a small portion of the tablet and look small. There is a solution though,
we can determine our own DPI level when loading resources and effectively force a
DPI based on screen resolution only when working with game images!
To work with such varied resolutions/DPIs and potential screen orientation changes
we need another tool in our arsenal: layout managers.
If you are familiar with AWT/Swing this should be pretty easy, Codename One allows
you to codify the logic that flows Components within the UI. We will use the layout
managers to facilitate that logic and preserve the UI flow when the device is rotated.

770

Appendix: Casual Game Programming

19.1.2.Resources
To save some time/effort we suggest using the ready made resource files linked in the
On The Web section below. I suggest skipping this section and moving on to the code,
however for completeness here is what we did to create these resources:
You will need a gamedata.res file that contains all the 52 cards as multi images using
the naming convention of rank suite.png example: 10c.png (10 of clubs) or ad.png
(Ace of diamonds).
To accomplish this we can create 52 images of roughly 153x217 pixels for all the cards
then use the designer tool and select Quick Add MultiImages from the menu. When
prompted select HD resolution. This effectively created 52 multi-images for all relevant
resolutions.
You can also modify the default theme that ships with the application in small ways
to create the white over green color scheme. Open it in the designer tool by double
clicking it and select the theme.
Then press Add and select the Form entry with background NONE , background color
6600 and transparency 255 .
Add a Label style with transparency 0 and foreground 255 and then copy the style
to pressed/selected (since its applied to buttons too).
Do the same for the SplashTitle / SplashSubtitle but there also set the
alignment to CENTER , the Font to bold and in the case of SplashTitle to Large
Font as well.

19.1.3.The Splash Screen

The first step is creating the splash animation as you can see in the screenshots in
figure 2.

771

Appendix: Casual Game Programming

Figure 19.1. Animation stages for the splash screen opening

animation
The animation in the splash screen and most of the following animations are achieved
using the simple tool of layout animations. In Codename One components are
automatically arranged into position using layout managers, however this isnt implicit
unless the device is rotated. A layout animation relies on this fact, it allows you to
place components in a position (whether by using a layout manager or by using
setX / setY ) then invoke the layout animation code so they will slide into their proper
position based on the layout manager rules.
You can see how we achieved the splash screen animation of the cards sliding into
place in Listing 1 within the showSplashScreen() method. After we change the
layout to a box X layout we just invoke animateHierarchy to animate the cards into
place.
Notice that we use the callSerially method to start the actual animation. This call
might not seem necessary at first until you try running the code on iOS. The first screen
of the UI is very important for the iOS port which uses a screenshot to speed startup.
If we wont have this callSerially invocation the screenshot rendering process will not
succeed and the animation will stutter.
We also have a cover transition defined here; its just a simple overlay when moving
from one form to another.

19.1.4.The Game UI
Initially when entering the game form we have another animation where all the cards
are laid out as you can see in Figure 19.2, Game form startup animation and deal
animation. We then have a long sequence of animation where the cards unify into
place to form a pile (with a cover background falling on top) after which dealing begins
772

Appendix: Casual Game Programming

and cards animate to the rival (with back only showing) or to you with the face showing.
Then the instructions to swap cards fade into place.

Figure 19.2. Game form startup animation and deal animation

This animation is really easy to accomplish although it does have several stages. In
the first stage we layout the cards within a grid layout (13x4), then when the animation
1
starts (see the UITimer code within showGameUI() ) we just change the layout to
a layered layout, add the back card (so it will come out on top based on z-ordering)
and invoke animate layout.
Notice that here we use animateLayoutAndWait , which effectively blocks the
calling thread until the animation is completed. This is a VERY important and tricky
subject!
Codename One is for the most part a single threaded API, it supports working on other
threads but it is your responsibility to invoke everything on the EDT (Event Dispatch
Thread). Since the EDT does the entire rendering, events etc. if you block it you will
effectively stop Codename One in its place! However, there is a trick: invokeAndBlock
is a feature that allows you to stop the EDT and do stuff then restore the EDT without
really stopping it. Its tricky, I wont get into this in this article (this subject deserves
an article of its own) but the gist of it is that you cant just invoke Thread.sleep() in a
Codename One application (at least not on the EDT) but you can use clever methods
such as Dialog.show() , animateLayoutAndWait etc. and they will block the
EDT for you. This is really convenient since you can just write code serially without
requiring event handling for every single feature.
Now that we got that out of the way, the rest of the code is clearer. Now we understand
that animateLayoutAndWait will literally wait for the animation to complete and
the next lines can do the next animation. Indeed after that we invoke the dealCard
method that hands the cards to the players. This method is also blocking (using and
1

https://www.codenameone.com/javadoc/com/codename1/ui/util/UITimer.html

773

Appendix: Casual Game Programming

wait methods internally) it also marks the cards as draggable and adds that drag and
drop logic which we will later use to swap cards.
Last but not least in the animation department, we use a method called replace to fade
in a component using a transition.
To handle the dealing we added an action listener to the deck button, this action listener
is invoked when the cards are dealt and that completes the game.
public class Poker {

private static final char SUITE_SPADE = 's';

private static final char SUITE_HEART = 'h';

private static final char SUITE_DIAMOND = 'd';

private static final char SUITE_CLUB = 'c';
private Resources cards;
private Form current;

private final static Card[] deck;

static {

// we initialize constant card values that will be useful later on

in the game

deck = new Card[52];

for(int iter = 0 ; iter < 13 ; iter++) {

deck[iter] = new Card(SUITE_SPADE, iter + 2);

deck[iter + 13] = new Card(SUITE_HEART, iter + 2);

deck[iter + 26] = new Card(SUITE_DIAMOND, iter + 2);

deck[iter + 39] = new Card(SUITE_CLUB, iter + 2);

/**
* We use this method to calculate a "fake" DPI based on screen
resolution rather than its actual DPI
* this is useful so we can have large images on a tablet
*/
private int calculateDPI() {

int pixels = Display.getInstance().getDisplayHeight() *

Display.getInstance().getDisplayWidth();
if(pixels > 1000000) {
}

return Display.DENSITY_HD;

if(pixels > 340000) {

}

return Display.DENSITY_VERY_HIGH;

774

Appendix: Casual Game Programming

if(pixels > 150000) {

return Display.DENSITY_HIGH;

return Display.DENSITY_MEDIUM;

/**
* This method is invoked by Codename One once when the application
loads
*/
public void init(Object context) {
try{

// after loading the default theme we load the card images as

a resource with

// a fake DPI so they will be large enough. We store them in a

resource rather

// than as files so we can use the MultiImage functionality

Resources theme = Resources.openLayered("/theme");

UIManager.getInstance().setThemeProps(theme.getTheme(theme.getThemeResourceNames()
[0]));
cards = Resources.open("/gamedata.res", calculateDPI());
} catch(IOException e) {

e.printStackTrace();

/**
* This method is invoked by Codename One once when the application
loads and when it is restarted
*/
public void start() {

if(current != null){
current.show();
return;

}
showSplashScreen();

/**
* The splash screen is relatively bare bones. Its important to have a
splash screen for iOS
* since the build process generates a screenshot of this screen to
speed up perceived performance
*/
public void showSplashScreen() {

775

Appendix: Casual Game Programming

final Form splash = new Form();

sides.

// a border layout places components in the center and the 4

// by default it scales the center component so here we configure
// it to place the component in the actual center
BorderLayout border = new BorderLayout();

border.setCenterBehavior(BorderLayout.CENTER_BEHAVIOR_CENTER_ABSOLUTE);
splash.setLayout(border);
// by default the form's content pane is scrollable on the Y axis
// we need to disable it here
splash.setScrollable(false);

Label title = new Label("Poker Ace");

// The UIID is used to determine the appearance of the component

in the theme

title.setUIID("SplashTitle");

Label subtitle = new Label("By Codename One");

subtitle.setUIID("SplashSubTitle");

splash.addComponent(BorderLayout.NORTH, title);
splash.addComponent(BorderLayout.SOUTH, subtitle);
Label as = new Label(cards.getImage("as.png"));
Label ah = new Label(cards.getImage("ah.png"));
Label ac = new Label(cards.getImage("ac.png"));
Label ad = new Label(cards.getImage("ad.png"));
// a layered layout places components one on top of the other in

the same dimension, it is

// useful for transparency but in this case we are using it for an

animation

final Container center = new Container(new LayeredLayout());

center.addComponent(as);
center.addComponent(ah);
center.addComponent(ac);
center.addComponent(ad);

splash.addComponent(BorderLayout.CENTER, center);
splash.show();

splash.setTransitionOutAnimator(CommonTransitions.createCover(CommonTransitions.SLIDE_V
true, 800));

776

Appendix: Casual Game Programming

// postpone the animation to the next cycle of the EDT to allow

the UI to render fully once

Display.getInstance().callSerially(new Runnable() {
public void run() {

// We replace the layout so the cards will be laid out in

a line and animate the hierarchy

// over 2 seconds, this effectively creates the effect of

cards spreading out

center.setLayout(new BoxLayout(BoxLayout.X_AXIS));
center.setShouldCalcPreferredSize(true);
splash.getContentPane().animateHierarchy(2000);

// after showing the animation we wait for 2.5 seconds and

then show the game with a nice

// transition, notice that we use UI timer which is

invoked on the Codename One EDT thread!

new UITimer(new Runnable() {

public void run() {

});

showGameUI();
}
}).schedule(2500, false, splash);

/**
* This is the method that shows the game running, it is invoked to
start or restart the game
*/
private void showGameUI() {
deck

// we use the java.util classes to shuffle a new instance of the

final List<Card> shuffledDeck = new

ArrayList<Card>(Arrays.asList(deck));
Collections.shuffle(shuffledDeck);
final Form gameForm = new Form();

gameForm.setTransitionOutAnimator(CommonTransitions.createCover(CommonTransitions.SLIDE
true, 800));
Container gameFormBorderLayout = new Container(new

BorderLayout());

// while flow layout is the default in this case we want it to

center into the middle of the screen

FlowLayout fl = new FlowLayout(Component.CENTER);

777

Appendix: Casual Game Programming

fl.setValign(Component.CENTER);

final Container gameUpperLayer = new Container(fl);

gameForm.setScrollable(false);

// we place two layers in the game form, one contains the contents

of the game and another one on top contains instructions

// and overlays. In this case we only use it to write a hint to

the user when he needs to swap his cards

gameForm.setLayout(new LayeredLayout());

gameForm.addComponent(gameFormBorderLayout);
gameForm.addComponent(gameUpperLayer);
// The game itself is comprised of 3 containers, one for each

player containing a grid of 5 cards (grid layout

// divides space evenly) and the deck of cards/dealer. Initially

we show an animation where all the cards

// gather into the deck, that is why we set the initial deck

layout to show the whole deck 4x13

final Container deckContainer = new Container(new

GridLayout(4, 13));

final Container playerContainer = new Container(new

GridLayout(1, 5));

final Container rivalContainer = new Container(new

GridLayout(1, 5));

// we place all the card images within the deck container for the

initial animation

for(int iter = 0 ; iter < deck.length ; iter++) {

Label face = new

Label(cards.getImage(deck[iter].getFileName()));
// containers have no padding or margin this effectively

removes redundant spacing

face.setUIID("Container");
deckContainer.addComponent(face);

// we place our cards at the bottom, the deck at the center and

our rival on the north

gameFormBorderLayout.addComponent(BorderLayout.CENTER,
deckContainer);
gameFormBorderLayout.addComponent(BorderLayout.NORTH,
rivalContainer);
gameFormBorderLayout.addComponent(BorderLayout.SOUTH,
playerContainer);
gameForm.show();

778

Appendix: Casual Game Programming

// we wait 1.8 seconds to start the opening animation, otherwise

it might start while the transition is still running

new UITimer(new Runnable() {
public void run() {

// we add a card back component and make it a drop target

so later players

// can drag their cards here

final Button cardBack = new

Button(cards.getImage("card_back.png"));
cardBack.setDropTarget(true);
// we remove the button styling so it doesn't look like a

button by using setUIID.

cardBack.setUIID("Label");
deckContainer.addComponent(cardBack);
// we set the layout to layered layout which places all

components one on top of the other then animate

// the layout into place, this will cause the spread out

deck to "flow" into place

// Notice we are using the AndWait variant which will

block the event dispatch thread (legally) while

// performing the animation, normally you can't block the

dispatch thread (EDT)

deckContainer.setLayout(new LayeredLayout());
deckContainer.animateLayoutAndWait(3000);

// we don't need all the card images/labels in the deck,

so we place the card back

// on top then remove all the other components

deckContainer.removeAll();
deckContainer.addComponent(cardBack);

// Now we iterate over the cards and deal the top card

from the deck to each player

for(int iter = 0 ; iter < 5 ; iter++) {

Card currentCard = shuffledDeck.get(0);

shuffledDeck.remove(0);
dealCard(cardBack, playerContainer,
cards.getImage(currentCard.getFileName()), currentCard);
currentCard = shuffledDeck.get(0);
shuffledDeck.remove(0);

779

Appendix: Casual Game Programming

dealCard(cardBack, rivalContainer,

cards.getImage("card_back.png"), currentCard);
}

// After dealing we place a notice in the upper layer by

fade in. The trick is in adding a blank component

// and replacing it with a fade transition

TextArea notice = new TextArea("Drag cards to the deck to

swap\ntap the deck to finish");

notice.setEditable(false);
notice.setFocusable(false);
notice.setUIID("Label");

notice.getUnselectedStyle().setAlignment(Component.CENTER);
gameUpperLayer.addComponent(notice);
gameUpperLayer.layoutContainer();
// we place the notice then remove it without the

transition, we need to do this since a text area

// might resize itself so we need to know its size in

advance to fade it in.

Label temp = new Label(" ");

temp.setPreferredSize(new Dimension(notice.getWidth(),

notice.getHeight()));
gameUpperLayer.replace(notice, temp, null);
gameUpperLayer.layoutContainer();
gameUpperLayer.replace(temp, notice,
CommonTransitions.createFade(1500));

the game

// when the user taps the card back (the deck) we finish
cardBack.addActionListener(new ActionListener() {

public void actionPerformed(ActionEvent evt) {

// we clear the notice text
gameUpperLayer.removeAll();

never takes new cards)

// we deal the new cards to the player (the rival

while(playerContainer.getComponentCount() < 5) {

Card currentCard = shuffledDeck.get(0);

shuffledDeck.remove(0);
dealCard(cardBack, playerContainer,
cards.getImage(currentCard.getFileName()), currentCard);
}

780

Appendix: Casual Game Programming

// expose the rivals deck then offer the chance to

play again...

for(int iter = 0 ; iter < 5 ; iter++) {

Button cardButton =

(Button)rivalContainer.getComponentAt(iter);

// when creating a card we save the state into

the component itself which is very convenient

Card currnetCard =
(Card)cardButton.getClientProperty("card");
Label l = new

Label(cards.getImage(currnetCard.getFileName()));
rivalContainer.replaceAndWait(cardButton,
l, CommonTransitions.createCover(CommonTransitions.SLIDE_VERTICAL,
true, 300));
}
// notice dialogs are blocking by default so its

pretty easy to write this logic

if(!Dialog.show("Again?", "Ready to play

Again", "Yes", "Exit")) {

}

Display.getInstance().exitApplication();

// play again

});

showGameUI();

}
}).schedule(1800, false, gameForm);

/**
* A blocking method that creates the card deal animation and binds
the drop logic when cards are dropped on the deck
*/
private void dealCard(Component deck, final Container destination,

Image cardImage, Card currentCard) {

final Button card = new Button();

card.setUIID("Label");
card.setIcon(cardImage);

// Components are normally placed by layout managers so setX/Y/

Width/Height shouldn't be invoked. However,

// in this case we want the layout animation to deal from a

specific location. Notice that we use absoluteX/Y

781

Appendix: Casual Game Programming

// since the default X/Y are relative to their parent container.
card.setX(deck.getAbsoluteX());

int deckAbsY = deck.getAbsoluteY();

if(destination.getY() > deckAbsY) {

card.setY(deckAbsY - destination.getAbsoluteY());

} else {

card.setY(deckAbsY);
}
card.setWidth(deck.getWidth());
card.setHeight(deck.getHeight());
destination.addComponent(card);
// we save the model data directly into the component so we don't

need to keep track of it. Later when we

// need to check the card type a user touched we can just use

getClientProperty

card.putClientProperty("card", currentCard);
destination.getParent().animateHierarchyAndWait(400);
card.setDraggable(true);
// when the user drops a card on a drop target (currently only the

deck) we remove it and animate it out

card.addDropListener(new ActionListener() {

public void actionPerformed(ActionEvent evt) {

});

evt.consume();
card.getParent().removeComponent(card);
destination.animateLayout(300);

public void stop() {

}

current = Display.getInstance().getCurrent();

public void destroy() {

}

static class Card {

private char suite;

private int rank;

public Card(char suite, int rank) {

this.suite = suite;
this.rank = rank;

782

Appendix: Casual Game Programming

}
private String rankToString() {
if(rank > 10) {

switch(rank) {
case 11:

return "j";

case 12:

return "q";

case 13:

return "k";

case 14:

}
}

return "a";

return "" + rank;

public String getFileName() {

return rankToString() + suite + ".png";

783

Chapter20.Working With The GUI

Builder
This section refers to the "old" GUI builder. Codename One is in the
process of replacing the GUI builder with a new version that uses a
radically different architecture.

20.1.Basic Concepts
The basic premise is this: the designer creates a UI version and names GUI
components. It can create commands as well, including navigation commands (exit,
minimize). It can also define a long running command, which will, by default, trigger a
thread to execute.
All UI elements can be loaded using the UIBuilder
2
Resources API?

class. Why not just use the

Since the Resources class is essential for using Codename One, adding the
UIBuilder as an import would cause any application (even those that dont use the
UIBuilder) to increase in size! We dont want people who arent using the feature to pay
the penalty for its existence!
The UIBuilder is designed for use as a state machine, carrying out the current state
of the application, so when any event occurs a subclass of the UIBuilder can just
process it. The simplest way and most robust way for changes is to use the Codename
One Designer to generate some code for you (yes, we know its not a code generation
tool, but there is a hack).
When using a GUI builder project, it will constantly regenerate the state machine base
class, which is a UIBuilder subclass containing most of what you need.
The trick is not to touch that code! DO NOT CHANGE THAT CODE!

Sure, you can change it and everything will be just fine, however if you make changes
to the GUI, regenerating that file will obviously lose all those changes, which is not
something you want!
1
2

https://www.codenameone.com/javadoc/com/codename1/ui/util/UIBuilder.html
https://www.codenameone.com/javadoc/com/codename1/ui/util/Resources.html

784

Working With The GUI Builder

To solve it, you need to write your code within the State machine class, which is a
subclass of the state machine base class, and just override the appropriate methods.
Then, when the UI changes, the GUI builder just safely overwrites the base class, since
you didnt change anything there.

20.1.1.Using Lists In The GUI Builder

The Codename One GUI builder provides several simplifications to the concepts
outlined below, you can build all portions of the list through the GUI builder, or build
portions of them using code if you so desire.
This is a step-by-step guide with explanations on how to achieve this. Again, you might
3
prefer using the MultiList component mentioned below, which is even easier to use.
Start by creating a new GUI form, set its scrollable Y to false, and set its layout to
border layout.

Figure 20.1. Set border layout

Next, drag a list into the center of the layout and you should now have a functioning
basic list with 3 items.

https://www.codenameone.com/javadoc/com/codename1/ui/list/MultiList.html

785

Working With The GUI Builder

Figure 20.2. Drag list onto form

Next, we will create the Renderer, which indicates how an individual item in the list
appears, start by pressing the Add New GUI Element button and select the Blank
Container option! Fill the name as MyRenderer or anything like that.

Figure 20.3. Set list renderer

Within the renderer you can drag any component you would like to appear, labels,
checkboxes, etc. You can nest them in containers and layouts as you desire. Give them
names that are representative of what you are trying to accomplish, e.g. firstName,
selected, etc.

786

Working With The GUI Builder

Figure 20.4. Add to renderer

You can now go back to the list, select it and click the Renderer property in order to
select the render container you created previously, resulting in something like this.

Figure 20.5. Preview list

Youll notice that the data doesnt match the original content of the list, that is because
the list contains strings instead of Hashtables. To fix this we must edit the list data.
You can place your own data in the list using the GUI builder, which is generally desired
regardless of what you end up doing, since this allows you to preview your design in
the GUI builder.
If you wish to populate your list from code, just click the events tab and press the
4
ListModel button, you can fill up the model with an array of Hashtables, as we will
explain soon enough (you can read more about the list model below).
4

https://www.codenameone.com/javadoc/com/codename1/ui/list/ListModel.html

787

Working With The GUI Builder

To populate the list via the GUI builder, click the properties of the list, and within them,
click the ListItems entry. The entries within can be Strings or Hashtables, however in
order to be customizable in the rendering stage, we will need them all to be Hashtables.
Remove all the current entries and add a new entry:

Figure 20.6. Add to list

After adding two entries as such:

Figure 20.7. Add items to list

We now have a customized list thats adapted to its renderer.

788