Skip Headers
Lightweight UI Toolkit Developer's Guide
Release 1.5
  Go To Table Of Contents
Go To Index


5 Using Dialogs

A Dialog is a form that occupies a part of the screen as a top level component. By default dialogs always appear as a modal entity to the user. Modality indicates that a dialog blocks the calling thread even if the calling thread is the Event Dispatcher Thread (EDT). Dialogs allow us to prompt users for information and rely on the information being returned as a response after the dialog show method. Each Dialog has a body that is located in the center of the dialog. The Body can contain a component, so you can use your own customer component or pre-built container.


A modal dialog does not release the block until a dispose method is called. For example, calling show() from another form does not release the block.

Dialog Types

For better user experience, dialogs have five types of alerts. The alert type indicates a sound to play or an icon to display if none is explicitly set:

By default the alerts are set to play the device alert sounds.

Icons are not currently provided by default, but you can manually add them to customized dialogs. Icons can be used to indicate the alert state, similar to JDialog icons in Swing. See (

Creating a Dialog

To create and show a dialog you can do the following:

The arguments to all of the show methods are standardized, though the number of arguments for each method varies. The static show methods provide support for laying out standard dialogs, providing icons, specifying the dialog title and text, and customizing the button text.

The following list describes each argument. To see the exact list of arguments for a particular method, see the Dialog API in the API documentation located in install-dir/docs/api/lwuit.

Return Types of Show Methods

You can use one of three convenient return value show methods: void, Command, or boolean.

  • Command returns the command object the user clicked. See the Command API in the API documentation found in install-dir/docs/api/lwuit.

  • The boolean value of true is returned when the OK command is pressed or if cancelText is null (meaning there is no cancel command text visible). It is false otherwise.

Non-Static Show Methods

The dialog API provides two non-static methods to create two more types of dialogs.

The first method takes no arguments and produces a dialog without any commands. The only way to close such a dialog is to invoke the dispose() method on the dialog. Since the dialog is blocking, meaning once the dialog is displayed its calling thread can not proceed until it is closed, the call to dispose must be made from a different thread. To do this, schedule the call to dispose with a timer thread. Note that the timer thread must be started before the dialog is displayed. This approach is referred to as an auto-closing dialog.

The second dialog type has five parameters. The first four are the four wing insets (top, bottom, left, and right) and the fifth parameter determines whether to include the Dialog title assigned through the dialog constructor (see Figure 5-1).

// Call show with inset parameters, 90, 10, 10, true);

Using the dispose() Method

The dispose methods closes the current dialog and returns to the parent form. When show() is used without arguments, one way to close the dialog is to set a timer to call dispose just before calling the show method (otherwise the dispose method is never performed).

Getting the User's Input from a Dialog

As mentioned in Non-Static Show Methods, return value types can be either Command or a boolean value. For example, if a user has a dialog with two commands, Approve and Decline, the user clicks and the selected command is returned. For the boolean return type, a true or false value indicates whether the user clicked the OK command.

Figure 5-1 Typical Dialogs

Description of Figure 5-1 follows
Description of "Figure 5-1 Typical Dialogs"