Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
XWT Documentation
What it is?
XWT is a declarative UI designed for Eclipse. It is a powerful and lightweight framework. It uses XML as UI markup language.
XWT simplifies UI programming. You can create visible UI elements in the declarative XML markup with a physical separation of the UI definition from the run-time logic. An XML based declarative language is very intuitive for creating interfaces ranging from prototype to production, especially for people with a background in web design and technologies.
Doc: Overview
Contents
Getting started
Hello, world!
Here is a simple example.
<Shell xmlns="http://www.eclipse.org/xwt/presentation" xmlns:x="http://www.eclipse.org/xwt"> <Shell.layout> <FillLayout/> </Shell.layout> <Button text="Hello, world!"> </Button> </Shell>
The same UI can be developed in Java corresponding:
Shell parent = new Shell(); parent.setLayout(new FillLayout()); Button button = new Button(parent, SWT.NONE); button.setText("Hello, world!");
To load and start a simple application, we use the class XWT:
Shell shell = XWT.load(file).getShell(); shell.pack(); shell.open(); while (!shell.isDisposed()) { if (!shell.getDisplay().readAndDispatch()) { shell.getDisplay().sleep(); } }
It is possible to load a UI resource under a Composite:
XWT.load(parent, uri);
Event Handling
In the previous example, we just rewrite Java code in XML. This example illustrates the separation between UI and event handling.
The appearance is defined in XWT.
<Shell xmlns="http://www.eclipse.org/xwt/presentation" xmlns:x="http://www.eclipse.org/xwt" x:Class="ui.EventHandler"> <Shell.layout> <GridLayout/> </Shell.layout> <Button text="Click Me!" SelectionEvent="clickButton"> </Button> </Shell>
The extension attribute x:Class declares the Java class to handle all events. The Button event is handled by clickButton method in the class ui.EventHandler. The association is setup during the loading:
package ui; import org.eclipse.swt.Event; import org.eclipse.swt.Button; public class EventHandler { protected void clickButton(Event event) { Button button = (Button )event.widget; button.setText("Hello, world!"); } }
When the button gets selected, the method clickButton is invoked to change the Button text to "Hello, world!".
==- Layout ==-
<Composite xmlns="http://www.eclipse.org/xwt/presentation" xmlns:x="http://www.eclipse.org/xwt"> <Composite.layout> <GridLayout numColumns="2"/> </Composite.layout> <Label text="Hello, world"/> <Text x:style="BORDER"> <Text.layoutData> <GridData horizontalAlignment="FILL" grabExcessHorizontalSpace="true"/> </Text.layoutData> </Text> </Composite>
- The simple element name (<Composite>) corresponds to a class name.
- The qualified element name (i.g. <Composite.layout>) corresponds to a property defined by an element.
- The default namespace corresponds to system packages.
- User defined package can be declared as a namespace in the format: ”clr-namespace:<package>=<jar>”
This is functionally equivalent to:
Composite parent = new Composite(shell, SWT.NONE); parent.setLayout(new GridLayout(2, false); Label label = new Label(parent, SWT.NULL); label.setText("Hello, world"); Text text = new Text(parent, SWT.BORDER); text.setLayoutData(new GridData(GridData.FILL_HORIZONTAL | GridData.GRAB_HORIZONTAL));
Data Binding
The DataBinding engine relies on Eclipse DataBinding component.
If we bind the text attribute of Label to a property “Name” of a Person, here is the data binding expression:
<Label text="{binding path=Name}"/>
It has the same result as following, but the expression is in pure XML:
<Label> <Label.text> <Binding path=”Name”/> </Label.text> <Label>
The data context of Label should be a person.
JFace integration
The following example shows the JFace direct integration with ListViewer.
We have a Class Company that has a name and a collection of Employee. The company is bound to the root Composite object. The child Text is bound to Name of company and ListViewer to property employees of type Java Collection.
<Composite xmlns="http://www.eclipse.org/xwt/presentation" xmlns:x="http://www.eclipse.org/xwt" xmlns:j="clr-namespace:jface.listviewer" x:DataContext="{StaticResource myCompany}"> <Composite.layout> <GridLayout numColumns="2"/> </Composite.layout> <x:Composite.Resources> <j:Company x:Key="myCompany" Name="Soyatec"> <j:Company.employees> <j:Employee Name="Thomas"/> <j:Employee Name="Jin"/> </j:Company.employees> </j:Company> </x:Composite.Resources> <Label text="Name"/> <Text text="{Binding Path=Name}"/> <ListViewer input="{Binding Path=employees}"> <ListViewer.contentProvider> <j:ContentProvider/> </ListViewer.contentProvider> <ListViewer.labelProvider> <j:LabelProvider/> </ListViewer.labelProvider> <ListViewer.control.layoutData> <GridData horizontalAlignment="FILL" grabExcessHorizontalSpace="true" horizontalSpan="2"/> </ListViewer.control.layoutData> </ListViewer> </Composite>
Extensibility and Re-usability
In case, if you have your own layout named as ui.MyGridLayout, it can be used directly. The code will be:
<Composite xmlns="http://www.eclipse.org/xwt/presentation" xmlns:x="http://www.eclipse.org/xwt" xmlns:y="cls-namespace:ui"> <Composite.layout> <y:MyGridLayout numColumns="2"/> </Composite.layout> <Label text="Hello, world"/> <Text x:style="BORDER"> <Text.layoutData> <GridData horizontalAlignment="FILL" grabExcessHorizontalSpace="true"/> </Text.layoutData> </Text> </Composite>
In the same way, a customized UI component can be used directly:
<Composite xmlns="http://www.eclipse.org/xwt/presentation" xmlns:x="http://www.eclipse.org/xwt" xmlns:y="cls-namespace:ui"> <Composite.layout> <GridLayout numColumns="2"/> </Composite.layout> <y:PersonView /> <y:PersonView.layoutData> <GridData horizontalAlignment="FILL" grabExcessHorizontalSpace="true"/> </y:PersonView.layoutData> </y:PersonView> </Composite>
Where the ui.PersonView is a UI component developed by two files:
XWT file PersonView.xwt
<Composite xmlns="http://www.eclipse.org/xwt/presentation" xmlns:x="http://www.eclipse.org/xwt" x:Class="ui.PersonView" xmlns:y="cls-namespace:ui"> <Composite.layout> <GridLayout numColumns="2"/> </Composite.layout> <Label text="Name"/> <Text x:style="BORDER"> <Text.layoutData> <GridData horizontalAlignment="FILL" grabExcessHorizontalSpace="true"/> </Text.layoutData> </Text> </Composite>
Java class PersonView.java
package ui; import org.eclipse.swt.widgets.Composite; public class PersonView extends Composite { ... }