eSWT API Specifications

This is the specification of the Embedded Standard Widget Toolkit (eSWT) and the SWT Mobile Extensions package which provide UI capabilities for embedded devices.

See:
Description

Packages

org.eclipse.ercp.swt.mobile	This package contains classes which are suitable for mobile devices.
org.eclipse.swt	SWT constants and error handling support.
org.eclipse.swt.browser	Optional Expanded eSWT Widgets
org.eclipse.swt.dnd	SWT Drag and Drop support.
org.eclipse.swt.events	SWT typed listener support.
org.eclipse.swt.graphics	SWT graphics classes.
org.eclipse.swt.internal
org.eclipse.swt.layout	This package contains the SWT layout classes.
org.eclipse.swt.widgets	Optional Expanded eSWT Widgets

This is the specification of the Embedded Standard Widget Toolkit (eSWT) and the SWT Mobile Extensions package which provide UI capabilities for embedded devices.

Copyright Notice and Disclaimers

Copyright (c) 2005 Eclipse Foundation. All rights reserved. Licensed under EPL

1. Introduction

The Embedded Standard Widget Toolkit (eSWT) subsets many core graphics and user interface API from the Standard Widget Toolkit (SWT). Applications can use this package to develop GUI applications for consumer devices such as mobile terminals and home devices.

eSWT is designed to be application model independent. This project does not define any specific application models defined by J2SE and J2ME like Applet, Xlet, or MIDlet, etc. eSWT provides a core UI API that Java applications can rely on and can be used in any application models or architectures that have support for full Java VM specification.

eSWT is also indepedent of J2ME UI APIs such as AWT/Swing and MIDP LCDUI. The minimal platform requirements are a JVM supporting the J2ME CLDC profile.

2. eSWT libraries

To enable eSWT to be used on devices with varying resources, eSWT is composed of three components. Each is provided as a separate JAR file. These are Core-eSWT, Expanded-eSWT, and SWT-Mobile-Extensions. The Core library is the minimum needed to use any eSWT API. Additional libraries may be installed to utilize additional function.

Core eSWT library
The Core eSWT library provides the minimum set of function needed to create a broad range of widget based applications for embedded devices. The API is a strict subset of the desktop SWT API. Thus, applications coding to this API are binary portable to desktop platforms. Core eSWT contains all classes in the following packages:

• org.eclipse.swt
• org.eclipse.swt.events
• org.eclipse.swt.graphics

and the listed classes in the following packages:

• org.eclipse.swt.layout
• FormAttachment
• FormData
• FormLayout
• org.eclipse.swt.widgets
• Listener
• Button
• Canvas
• Combo
• Composite
• Control
• Decorations
• Dialog
• Display
• Event
• FileDialog
• Item
• Label
• Layout
• List
• Menu
• MenuItem
• MessageBox
• ProgressBar
• Scrollable
• ScrollBar
• Shell
• Slider
• Synchronizer
• Text
• TypedListener
• Widget

Expanded eSWT library
The Expanded eSWT library provides a set of widgets which tend to require more resources and larger screen sizes than widgets in the Core library. These widgets are still a strict subset of desktop SWT API. Expanded eSWT contains all classes in the following packages:

• org.eclipse.swt.browser
• org.eclipse.swt.dnd

and the listed classes in the following packages:

• org.eclipse.swt.layout
  • FillLayout
  • GridData
  • GridLayout
  • RowData
  • RowLayout
• org.eclipse.swt.widgets
  • ColorDialog
  • DirectoryDialog
  • FontDialog
  • Table
  • TableColumn
  • TableItem
  • Tree
  • TreeItem

SWT Mobile Extensions
The SWT Extensions library provides widgets which are most useful for mobile devices with small screens and limited user input options. Applications which require this package will not be portable to the desktop unless a compatibility library is included. SWT Mobile Extensions contains all classes in the following package:

• org.eclipse.ercp.swt.mobile

3. Design Issues

eSWT is very oriented toward using a platform's native capabilities and native UI look and feel . Therefore, some API parameters are considered as "hints" to the eSWT implementation. These hints are used in a manner consistent with the particular platform eSWT is running on. For instance, on some platforms, certain user interface properties can not be changed, such as foreground and background colors and fonts.

4. Related Materials

See www.eclipse.org/ercp for related requirements and desgin documents.

5. Status of this document and change history

Date	Version	Description
2005/January/24	Public Review Draft	First time all packages have been placed together for review
2005/Feburary/14	Final Review API Spec	Function approved by work group, API signatures may still be modified if required up until Final Approval date
2005/March/09	Final Review Update	Some signatures modified for API consistency, Many JavaDoc fixes to solidify spec.
2005/April/25	Final Specification	Transform API, RichTextBox widget, Program package removed. API documentation clarifications made.
2005/May/20	Specification Revision	TaskTip constructor parameter changed. GC.get/setAlpha further documented.
2005/June/07	Specification Revision	TaskTip default values specified. Command "focus context" clarified. Core sync-ed with desktop SWT.
2005/July/07	Specification Revision	Updates from desktop SWT, clarify several Mobile Extension widgets.
2005/July/25	Specification Revision	Clarify Table, Tree, QueryDialog, SortedList.
2005/November/2	Specification Revision	Remove get/setMinimumSize, minor clarifications

Core changes since last draft

Thu Oct 20 14:27:13 CDT 2005	lkues

	javadoc fix

	Device.java 1.7

Tue Sep 27 12:46:35 CDT 2005	lkues

	doc update

	Combo.java 1.6

Wed Aug 17 14:00:50 CDT 2005	lkues

	remove get/set minimumSize API

	Shell.java 1.7

Mon Aug 08 16:19:32 CDT 2005	lkues

	Shell getMinimumSize API

	Shell.java 1.6

Mon Aug 08 09:18:52 CDT 2005	lkues

	remove advanced layout methods

	Composite.java 1.6

Fri Aug 05 14:59:29 CDT 2005	lkues

	cleanup

	SWT.java 1.13

Expanded changes since last draft

Thu Aug 18 13:37:52 CDT 2005	lkues

	cleanup

	GridData.java 1.7

Mon Aug 08 12:11:32 CDT 2005	lkues

	spec cleanup

	GridData.java 1.6

Fri Aug 05 15:22:55 CDT 2005	lkues

	spec cleanup

	RowData.java 1.4
	GridData.java 1.5

Mobile Extensions changes since last draft

Tue Nov 01 11:05:08 CST 2005	mrogalski

	clarify layout non-support

	CaptionedControl.java 1.13

Thu Sep 29 07:30:17 CDT 2005	mrogalski

	spelling/grammar corrections

	TimedMessageBox.java 1.8
	HyperLink.java 1.3
	ConstrainedText.java 1.11

Fri Sep 02 13:10:39 CDT 2005	mrogalski

	Show how to set global commands on MPD

	MultiPageDialog.java 1.15