Introduction

As increasingly sophisticated mobile platforms proliferate, the demand for mobile computing will increase. The embedded Standard Widget Toolkit (eSWT) Mobile Extension is an Eclipse technology that can be used to develop native-looking Java applications for a variety of mobile phones.

eSWT provides standard embedded widgets to build mobile applications. It is part of the embedded Rich Client Platform (eRCP) project. eSWT is primarily concerned with meeting the functional and user experience requirements of mobile devices. eSWT provides efficient, portable access to the user-interface facilities of the devices on which it is implemented. It is a subset of the desktop SWT API. For deployment adaptability, the API is divided into two packages:

• Core eSWT contains the base function and simple widgets.
• Expanded eSWT contains more complex widgets (Table, Tree, WebBrowser) and additional layouts and dialogs.

This article assumes you have a fundamental understanding of eSWT and eRCP.

Back to top

Overview

Table 1 provides an overview of the eSWT mobile extensions. You can also view the class hierarchy.

The rest of this article explores the first five mobile controls. Download the sample code snippets used in this article.

Back to top

CaptionedControl

You can use CaptionedControl to display a label, or caption, in front of a control. An optional trailing text can be used after the control, such as indicating units of measurement, for example.

Determining which control has focus can be difficult on mobile devices where lighting conditions are often less than optimal. Use CaptionedControl to caption a control with a label that shows focus highlighting whenever the control has focus. With an entire label highlighted, it's easy to find the focus point.

You can use the following mutually exclusive styles to define a CaptionedControl.

LEFT_TO_RIGHT

The default style. Elements inside CaptionedControl are aligned from left to right.

RIGHT_TO_LEFT

Elements inside CaptionedControl are aligned from right to left.

CaptionedControl has several getters and setters to operate on its attributes. Listing 1 shows a code sample that creates two CaptionedControls.

CaptionedControl captionedControl = new CaptionedControl(shell, SWT.LEFT_TO_RIGHT);
captionedControl.setText("Name: ");
Text text = new Text(captionedControl, SWT.SINGLE);
text.setText("Dr. John Wimer");
captionedControl.setTrailingText("Surgeon");
Image image1 = new Image(display,"res/surgeon.png");
captionedControl.setImage(image1);

CaptionedControl captionedControl2 = new CaptionedControl(shell, SWT.LEFT_TO_RIGHT);
captionedControl2.setText("Name: ");
Text text2 = new Text(captionedControl2, SWT.SINGLE);
text2.setText("Jessica");
captionedControl2.setTrailingText("Receptionist");
Image image2 = new Image(display,"res/receptionist.png");
captionedControl2.setImage(image2);

The code snippet above creates two text controls captioned by CaptionedControl. The example also creates two images to better describe their job titles. The code result is shown in Figure 1, with the focused control highlighted.

Back to top

ConstrainedText

ConstrainedText is a single-line text control that constrains the style the user may input. This control limits the characters users can enter to make data entry more efficient. It also limits the characters than can be entered within the field.

You can use the following mutually exclusive styles to create different types of ConstrainedText.

DECIMAL

The decimal input style allows numeric values with optional decimal fractions. For example, -123, 0.123, or .5 are all valid input.

NUMERIC

The numeric input style allows numeric values.

PHONENUMBER

The phone number input style allows numeric values with optional phone-specific characters, such as +, * and #.

The code sample in Listing 2 creates different types of ConstrainedText.

Composite composite1 = new Composite(shell,SWT.NONE);		
composite1.setLayout(new RowLayout(SWT.HORIZONTAL));	
Label phoneNumber = new Label(composite1,SWT.NONE);
phoneNumber.setText("Phone Number: ");
ConstrainedText cT1 = new ConstrainedText(composite1, SWT.BORDER, 
                                          ConstrainedText.PHONENUMBER);

Composite composite2 = new Composite(shell,SWT.NONE);		
composite2.setLayout(new RowLayout(SWT.HORIZONTAL));	
Label decimal = new Label(composite2,SWT.NONE);
decimal.setText("Decimal: ");
ConstrainedText cT2 = new ConstrainedText(composite2, SWT.BORDER, 
                                          ConstrainedText.DECIMAL);

Composite composite3 = new Composite(shell,SWT.NONE);		
composite3.setLayout(new RowLayout(SWT.HORIZONTAL));	
Label numeric = new Label(composite3,SWT.NONE);
numeric.setText("Numeric: ");
ConstrainedText cT3 = new ConstrainedText(composite3, SWT.BORDER, 
                                          ConstrainedText.NUMERIC);

The code above creates three ConstrainedTexts that limit the input to only phone number, with decimal and numeric styles. The result is shown in Figure 2 with some sample input text.

Back to top

DateEditor

DateEditor is a special data-entry control that lets users enter or choose a date. The return value of getDate() is an instance of a Date class.

The default locale and time zone for the date and time formatting reflects the current configuration in the device. If a date is not set, the current date is the default used. Applications may call setTimeZone(timeZone) to change the differential added to Coordinated Universal Time (UTC) time. This change only affects the widget instance and does not affect other applications.

You can use the following mutually exclusive styles to create different types of DateEditor.

DATE

A date entry type for year, month, and day.

DATE_TIME

An entry type for date and time.

DURATION

An entry type for a period of time in hours, minutes, and seconds.

OFFSET

An entry type for a period of time in hours, minutes, and seconds that can be subtracted or added to another time value.

With these styles, you can use the logical bitwise operation or with one of the widget-specific styles hints:

COMPACT

A hint that the widget should be displayed in a format that's smaller or less full-featured.

FULL

A hint that the widget should be displayed in a format that's full-featured and emphasizes ease of use, rather than compactness.

There are several getters and setters to set or get the date and time. You can also use setTimeZone() to change the application time zone. eRCP javadoc has details about usage.

Listing 3 shows sample code that creates different types of DateEditor.

DateEditor dateEditor1 = new DateEditor(composite, SWT.NONE, DateEditor.DATE);
DateEditor dateEditor2 = new DateEditor(composite, SWT.NONE, DateEditor.TIME);
DateEditor dateEditor3 = new DateEditor(composite, SWT.NONE, 
                                        DateEditor.DURATION);
DateEditor dateEditor4 = new DateEditor(composite, SWT.NONE, 
                                        DateEditor.OFFSET);		
dateEditor3.setTime(1000);
dateEditor4.setTime(-1000);

Four types of DateEditor are created.

The first DateEditor is a date-style control. The user can click on the anchor on the right to bring up a date/time selector.

Back to top

ListBox

ListBox represents a selectable UI object that displays a list of items, such as text and icons from a data model. Each list item may include combinations of heading text, heading icons, detail text, and detail icons. You can use styles and modifiers to set the layout and display of ListBox.

Unlike List, data contained in ListBox is from a array of ListBoxItem, rather than adding or inserting one by one, to provide an MVC model. Heading and detail icons in a ListBoxItem will be displayed at the size provided, or stretched to fit the ListBox styles. To make the representation consistent, all heading icons should be the same size, and all detail icons should be the same size for any one list. Elements of a ListBoxItem that are null won't be displayed in the ListBox layout.

You can use the following mutually exclusive styles to create different types of ListBox:

LB_STYLE_NO_HEADING_TEXT

Displays single-line items with only one column (detail text). It is also the default style if the style attribute is not specified.

LB_STYLE_1LINE_ITEM

Displays single-line items with two columns (heading text and detail text).

LB_STYLE_2LINE_ITEM

Displays double-line items — one column with heading and detail combined.

The styles above can be bitwise ORed with any number of modifier styles below.

LB_MOD_SHOW_SELECTION_NUMBER

Shows a single-digit number aligned with each item, which may be used to select the item. For example, 1 means press 1 on the keypad to select this item.

LB_MOD_SHOW_HEADING_ICONS

Shows the icon associated with heading text.

LB_MOD_SHOW_DETAIL_ICONS

Shows icons associated with detail text.

Since ListBox is an MVC widget, when you change anything in the model part (ListBoxItem), you can use the following methods to keep the view part synced with the model's change.

setDataModel(ListBoxItem[] items)

Sets the data model of this ListBox. This array will be used in the lifetime of the ListBox unless you set another array as ListBox's data model.

public void refreshItem(int index)

When you make a change to one ListBoxItem, you can notify this ListBox that the data for the item at the given index has been updated and the item display needs to be refreshed.

refreshList()

When you make changes to several ListBoxItems, you can use this to refresh the entire list display in this ListBox.

The code in Listing 4 creates one array of ListBoxItem and sets it as the model for different types of ListBox.

int[] modes={
  ListBox.LB_STYLE_2LINE_ITEM | ListBox.LB_MOD_SHOW_HEADING_ICONS |
  ListBox.LB_MOD_SHOW_DETAIL_ICONS,
  ListBox.LB_STYLE_1LINE_ITEM | ListBox.LB_MOD_SHOW_HEADING_ICONS |
  ListBox.LB_MOD_SHOW_DETAIL_ICONS,
  ListBox.LB_STYLE_1LINE_ITEM | ListBox.LB_MOD_SHOW_HEADING_ICONS |
  ListBox.LB_MOD_SHOW_DETAIL_ICONS | ListBox.LB_MOD_SHOW_SELECTION_NUMBER,
  ListBox.LB_STYLE_1LINE_ITEM | ListBox.LB_MOD_SHOW_DETAIL_ICONS |
  ListBox.LB_MOD_SHOW_SELECTION_NUMBER,
  ListBox.LB_STYLE_NO_HEADING_TEXT|ListBox.LB_MOD_SHOW_DETAIL_ICONS,
  ListBox.LB_STYLE_NO_HEADING_TEXT
  };
  
// Create the data modal
ListBoxItem[] listboxitems = new ListBoxItem[3];

// Get images
Image surdetail = new Image(display, "res/ambunance-2-24x24.png");
Image surheading = new Image(display, "res/surgeon-32x32.png");
Image nurdetail = new Image(display, "res/syringe-24x24.png");
Image nurheading = new Image(display, "res/nurse-32x32.png");
Image pragdetail = new Image(display, "res/red-cross-24x24.png");
Image pregheading = new Image(display, "res/pregnant-32x32.png");

listboxitems[0] = new ListBoxItem("Bill Marshall", surdetail, "Surgeon", surheading);
listboxitems[1] = new ListBoxItem("Nancy Moore", nurdetail, "nurse", nurheading);
listboxitems[2] = new ListBoxItem("Lily Davis", pragdetail, "Pregnant", pregheading);

// Then we call creation of ListBox several times with different 
// styles to see different visual effect
ListBox[] listbox = new ListBox[6];
for (int i=0; i<6; i++) {
  // create new Listbox
  listbox[i] = new ListBox(composite, SWT.SINGLE, modes[i] );
  // add the ListBoxItems to the ListBox
  listbox[i].setDataModel(listboxitems);
}

The result of the code snippet above is shown below.

Back to top

ListView

ListView allows users to select one or more items from a collection of items that can be displayed in a multi-column format with different styles. It is similar to List, but also provides icon support in each item for a more fancy visual appearance.

ListView lays out its children items in one or more columns from top to bottom. If a layout-orientation hint is not specified, the implementation chooses the orientation. If there is only enough screen width for one column, the list scrolls vertically. If there is room to display multiple columns within the widget, the list scrolls horizontally. The list never scrolls in more than one direction. The layout orientation may be set at runtime by calling the setLayout(int) method.

The item-density hint determines the size and positioning of items in order to fit more or less within the widget. Applications can query the preferred sizes of the icons for each density level. The sizes may be diverse in different platforms. When the given icons do not match the preferred size, the implementation may adjust icon sizes without throwing any exception. Applications can change the item density level at runtime by calling the setLayoutDensity(int) method.

ListView has two style variables: SWT and density. With the SWT style, you can specify the selection type (single or multiple) and layout style (vertical or horizontal). For example, you can use SWT.SINGLE | SWT.VERTICAL to create a single selection, vertical layout ListView. The following are mutually exclusive styles you can use to create a ListView.

LOW

Low density

MEDIUM

Medium density

HIGH

High density

Listing 5 shows a code sample that creates a ListView containing 20 items, all of which are added with icons. It also creates two commands to demonstrate the density visual effect.

final ListView lv = new ListView(composite, SWT.MULTI, ListView.HIGH);

//set Image array
Image[] image = new Image[4];
image[0] = new Image(Display.getDefault(), "res/pregnant-32x32.png");
image[1] = new Image(Display.getDefault(), "res/nurse-32x32.png");
image[2] = new Image(Display.getDefault(), "res/surgeon-32x32.png");
image[3] = new Image(Display.getDefault(), "res/pill-32x32.png");
lv.setSize(200,250);

//Create a Command for setting low density
Command lowCommand = new Command(lv, Command.SELECT, 0);
lowCommand.setText("LOW");
lowCommand.addSelectionListener(new SelectionListener(){
  public void widgetSelected(SelectionEvent e) {
  	lv.setLayoutDensity(ListView.LOW);
  }
  public void widgetDefaultSelected(SelectionEvent e) {
  }});

//Create a Command for setting high density
Command midCommand = new Command(lv, Command.SELECT, 0);
midCommand.setText("MEDIUM");
midCommand.addSelectionListener(new SelectionListener(){
  public void widgetSelected(SelectionEvent e) {
    lv.setLayoutDensity(ListView.MEDIUM);
  }
  public void widgetDefaultSelected(SelectionEvent e) {
}});

//add ListView items
for (int i=0; i<20; i++) {
  lv.add("item"+i, image[i % 4]);
}		

The result of the code above is shown in Figure 6 with medium density and in Figure 7 with low density.

Back to top

Conclusion

This article introduced you to the eSWT mobile extension. You also learned about five mobile controls. You can review the code samples in Download if you have questions.

Part 2 of this series explores more eSWT mobile extension classes and interfaces.

Back to top

Download

Information about download methods

Resources

Learn

• "Explore Eclipse's embedded Rich Client Platform" offers a general introduction to eRCP.
  
  
• "Develop eRCP applications with Eclipse" is a how-to guide for developing eRCP applications.
  
  
• Visit eRCP to learn more about eRCP.
  
  
• To listen to interesting interviews and discussions for software developers, check out developerWorks podcasts.
  
  
• Stay current with developerWorks' Technical events and webcasts.
  
  
• Follow developerWorks on Twitter.
  
  
• Check out upcoming conferences, trade shows, webcasts, and other Events around the world that are of interest to IBM open source developers.
  
  
• Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
  
  
• Watch and learn about IBM and open source technologies and product functions with the no-cost developerWorks On demand demos.
  
  

Get products and technologies

• Innovate your next open source development project with IBM trial software, available for download or on DVD.
  
  
• Download IBM product evaluation versions or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  

Discuss

• Participate in developerWorks blogs and get involved in the developerWorks community.
  
  

About the authors

Uriel Liu is a software developer at the IBM China Software Development Lab and works in WED client technology. He is also a committer on the eRCP project.

Eric Hsu is a software developer at the IBM China Software Development Lab in Taipei. He works in Lotus Expediter client technology and Eclipse eRCP project development. He is a committer to the Eclipse eRCP project, as well.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Overview
• CaptionedControl
• ConstrainedText
• DateEditor
• ListBox
• ListView
• Conclusion
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

Spring, JRuby, and Ajax development is easier with WebSphere Application Server - a smart Java 5 and J2EE Web services-based application server.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and other best-of-breed open source software such as OpenEJB, Apache Axis, and Apache Derby.
• Article: The article leverage the Spring Framework and the WebSphere Application Server to improve your J2EE project productivity.
• Tutorial: See how the free WebSphere Application Server and XML can improve the efficiency of your JRuby on Rails and Ajax development.
• Buy: WebSphere Application Server - Express

My developerWorks community

Dig deeper into Open source on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers