LWUIT Mini FAQ

This appendix addresses common questions about LWUIT.

Question: Performance on the Java ME SDK or the Wireless Toolkit is very slow, what is the problem?

Answer: There are documented issues of slow performance due to Hyperthreading.

• 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.

Question: How does painting in LWUIT differ from Swing/AWT?

Answer: 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.

Question: Scrolling isn't working like I expect, ewhat went wrong?

Answer: There are several common possibilities.

• 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.

Question: What is a painter? Why not just use an image?

Answer: 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.

Question: Is LWUIT identical across all platforms?

Answer: 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 Theme Creator 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.

Question: Does LWUIT support 3 SoftButton devices?

Answer: 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.

Question: A device doesn't seem to work with LWUIT. What should I do?

Answer: Is it a MIDP 2.0/CLDC 1.1 device? If it is then please mail lwuit@sun.com 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?

Question: I want my application to look "native" on the device. Is there any way to accomplish that?

Answer: 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.

Question: The UI for my touch screen phone seems too small for my fingers. How do I make the UI more appropriate for such a device?

Answer: 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.

Question: Why am I getting memory errors in LWUIT? Why is LWUIT is consuming a lot of memory in my memory monitor?

Answer: 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.

Question: Why won't my list/text area scroll? Why does my list/text area jump around?

Answer: 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.

Question: How can I make scrolling more elaborate? Does LWUIT only support scrolling based on focus? Why isn't scrolling of an element larger than screen size supported?

Answer: LWUIT features an open interface for scrolling, allowing any component to define the way in which it wishes to scroll. This interface is used by the TextArea and List components to implement their internal scroll functionality.

LWUIT doesn't scroll containers. Instead it provides focus traversal, which causes scrolling to the focused component. This is a very powerful approach (and very common on small devices) since it allows easy interaction. However, in some circumstances (mostly viewers) LWUIT focus-based scrolling doesn't behave as expected. Since the scrolling architecture is exposed, developers can extend container and override the scrolling/key handling to behave as expected.

Scrolling a single component which is larger than the screen isn't supported by LWUIT containers. (This is a very difficult edge case for focus based scrolling). Scrolling multiple smaller components is not a problem.

Community member Elliot Long contributed his own solution to "visual scrolling" which allows scrolling without focus. The LWUIT blog covers simple image scrolling and explains the details here.

Question: How do I change the appearance of the list? Remove the numbers from the side etcetera? Can I nest containers in the list?

Answer: List is 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.

Question: My application freezes or stalls. How do I fix this?

Answer: 99% of the problems of this type are related to Event Dispatch Thread (EDT) violations. 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/callSeriallyAndWait. A different option is to use invokeAndBlock.

Question: I'm not opening any threads, why am I having problems?

Answer: 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.

Question: Does anything work from a separate thread?

Answer: There are no guarantees, but repaint() should generally work from every thread and show() should as well.

Question: How do I reposition/resize a dialog?

Answer: 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.

Question: How do I show Video?

Answer: Use MMAPI to create a Player object, then submit it to the MediaComponent class.

Question: How do I show SVG/3D?

Answer: Use the M3G API or the SVGImage API to place such elements in the UI.

Question: Can I create my own components?

Answer: Everything in LWUIT is fully extensible.You can derive from any component and extend it. It is demonstrated in the Chapter 16, Authoring Components and it is discussed extensively in the blog.

Question: I'm trying to display an animated gif. Why isn't it working?

Answer: Animated gifs can be shown in MIDP using the MMAPI and MediaComponent (see the MMAPI question). LWUIT has special support for StaticAnimation which is a LWUIT specific format very similar to the animated gif. Both the Theme Creator and the Ant task accept animated GIF files to create static animations.

Question: Why am I having problems on the BlackBerry?

Answer: The BlackBerry VM has some issues with linking to classes that aren't on the device. A BlackBerry-specific version built with the BlackBerry VM is necessary. See the LWUIT-incubator project for a community built port for the BlackBerry. There is another BlackBerry port within the LWUIT project version control system.

Question: I'm having issues on a Windows Mobile device?

Answer: 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.

Question: How do I create resource (.res) files?

Answer: Use the Theme Creator (formerly the Resource Editor) or the Ant task.

Question: What is the difference between the Theme Creator (formerly the Resource Editor) and the Ant task?

Answer: The difference is mainly in the use case, the ant tool is designed mostly for developer related resources (locales, application images, etcetera). The Theme Creator is designed for use by graphics designers.