|Lightweight UI Toolkit Developer's Guide
This appendix addresses common questions about LWUIT.
Performance on the Java ME SDK or the Wireless Toolkit is very slow, what is the problem?
There are documented issues of slow performance due to Hyperthreading.
Slow loopback in the network interface (often caused by miss-configured networking) also impacts performance because the toolkit uses network calls to perform all drawing.
Sprint WirelessToolkit versions 3.2 and higher do not have these performance issues because they feature a different architecture.
Generally both are very much alike. There are, however, some minor key differences that might “bite” an unsuspecting Swing/AWT developer:
LWUIT clears the background – when drawing the component LWUIT makes sure to first clear the background for the component using the painters for its parents if necessary.
LWUIT translates to parent component coordinates – A Swing component always starts at 0, 0. This is because Graphics.translate is invoked with the X and Y coordinates of the component. In LWUIT this is done only for parent containers, which is why the components in LWUIT must be drawn in their X and Y location. The problem with this approach is that drawing in 0,0 often works for the first component in the container and fail for subsequent components.
LWUIT doesn't make a distinction between paintContent or paintChildren – All calls in LWUIT lead to paint and paintBorder. There is no separate call for painting the children of a container.
Scrolling isn't working like I expect. What went wrong?
You nested a scrollable component within another scrollable component (this is technically legal but might look odd). By default the form is scrollable so just try invoking setScrollableY(false) on the form.
Scrolling behaves based on the amount of space allocated by the layout manager. Some layout managers do everything to prevent scrolling (such as grid layout) while the box layout tries to increase size as much as possible. Read the documentation for your layout manager of choice.
For group layout components (generated by the UI builder) you must make sure to mark components to grow and verify that they indeed do so in preview mode. You must size the container to match the size of the component boundaries, otherwise the container size is hardcoded.
The idea behind a painter is simple, provide flexibility to the developer and allow the developer to define rendering suitable for his needs on any device. While images provide decent flexibility for artists' ideas, painters provide limitless flexibility:
A developer can use a relatively low overhead gradient painter to get a very compelling look without a single additional image file. Furthermore, the gradient adapts nicely to any screen resolution.
In high-end devices that support SVG, etcetera, painters can use SVG to render and scale vector graphics rather than scale raster graphics. This increases the application UI fidelity.
Is LWUIT identical across all platforms?
Yes and No.
The basic core API is the same on most tested platforms and is binary compatible, allowing MIDP applications to run on Java SE (for example, in the Resource Editor actual MIDlet code is running in Java SE).
The catch is in several details:
Some components aren't available in other platforms: M3G, Media (sometimes available), and SVG.
Rendering might seem different on other platforms due to platform issues. For example, in some platforms LWUIT takes advantage of anti-aliasing. System fonts look completely different between platforms and bitmap fonts look odd in some platforms that don't properly support alpha channels.
Different platforms have different performance characteristics.
For more details on these issues check out the portability chapter.
Does LWUIT support 3 SoftButton devices?
Yes, 3 SoftButton mode is implemented in display. However, since there is no reliable way to detect 3 SoftButton phones this features can be activated either programmatically or through a JAD file attribute.
A device doesn't seem to work with LWUIT. What should I do?
Is it a MIDP 2.0/CLDC 1.1 device? If it is then please mail firstname.lastname@example.org with the following additional details:
Does LWUIT hello world work on the device?
Does the LWUIT UIDemo work on the device?
What is the resolution+color depth of the device, and how much memory is allocated for Java?
I want my application to look "native" on the device. Is there any way to accomplish that?
While LWUIT is designed to do the exact opposite (support your own look and feel) a native look and feel can be partially achieved if you implement a theme or look and feel that resembles the native look.
This won't work very well on most devices since there is no way to detect if the user switched the default theme.
Downloadable themes are probably a good approach for a strong user community.
Use a global padding setting in the theme to increase the size of all widgets to a point where they are big enough for a finger tip.
Check that your application doesn't hold onto pointers for components. Because a component references its parent component, holding onto a single button can keep an entire form with all its content in memory... LWUIT allocates and discards frequently to allow for a small memory footprint. This causes the graph of free memory to fluctuate but the alternative of caching would be worse for highly constrained devices. Check out the LWUIT blog for more information on the subject of tracking and identifying memory issues.
Why won't my list/text area scroll? Why does my list/text area jump around?
You need to disable the scrolling for the form using myForm.setScrollable(false) and you should place the list in the center of a border layout. For deeper understanding of why this is required, read the next question about scrolling.
How do I change the appearance of the list? Remove the numbers from the side etcetera? Can I nest containers in the list?
Listis designed for a very large number of element and fast traversal. You can use its cell renderer facility to customize it any way you want as explained here. How the list can scale and grow is explained here and additionally here.
My application freezes or stalls. How do I fix this?
What is the Event Dispatch Thread (EDT)?
The EDT broadcasts all the events in LWUIT. It is also responsible for drawing all elements on the screen.The EDT thread is responsible for drawing all screen elements, if it is blocked by a long running operation elements won't update and key/pointer events won't be received. The solution is to use threads for such long running tasks, however interaction with LWUIT can only be performed on the EDT. To return into the EDT you can use Display.callSerially and callSeriallyAndWait. A different option is to use invokeAndBlock.
I'm not opening any threads, why am I having problems?
A typical application always uses at least two threads, lifecycle and the EDT. The lifecycle thread is the callback thread used for the application. For example, in MIDP the startApp method is invoked from the MIDP thread which is different from the EDT.
Does anything work from a separate thread?
There are no guarantees, but repaint() should generally work from every thread and show() should as well.
How do I reposition/resize a dialog?
Use a Dialog instance and a version of show which accepts 4 integer values to position the dialog. You can use the set the default dialog position to simplify dialog positioning.
How do I show Video?
Use MMAPI to create a Player object, then use the VideoComponent class.
Can I create my own components?
Everything in LWUIT is fully extensible.You can derive from any component and extend it. It is demonstrated in the Chapter 14 and it is discussed extensively in the blog at http://codename-1.blogspot.com/.
I'm trying to display an animated gif. Why isn't it working?
Animated gifs can be shown in MIDP using the MMAPI and VideoComponent (see How do I show Video?). LWUIT has special support for StaticAnimation which is a LWUIT specific format very similar to the animated gif. Both the Resource Editor and the Ant task accept animated GIF files to create static animations.
I'm having issues on a Windows Mobile device?
Windows mobile VMs vary significantly in their quality. If the VM is giving you problems try the Phone ME open source VM port for Windows mobile devices.
How do I create resource (.res) files?
What is the difference between the Resource Editor and the Ant task?
The difference is mainly in the use case, the ant tool is designed mostly for developer related resources (locales, application images, etcetera). The Resource Editor is targeted for use by graphic designers.