Jump to: navigation, search

Difference between revisions of "E4/DeclarativeUI/XWT"

(1. Hello, world)
(Replacing page with 'This page is moved to [http://wiki.eclipse.org/E4/XWT http://wiki.eclipse.org/E4/XWT]')
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Name of Technology ==
+
This page is moved to [http://wiki.eclipse.org/E4/XWT http://wiki.eclipse.org/E4/XWT]
XWT Here is a presentation of our vision [[Image:XWT.pdf]]
+
 
+
== Purpose ==
+
Adopt a direct mapping XML to SWT/JFace with the support of JFace DataBinding
+
 
+
== Contact ==
+
[mailto:yves.yang@soyatec.com Yves YANG]
+
 
+
== Committers ==
+
Yves YANG, Thomas Guiu and others
+
 
+
== Current License ==
+
XWT is an Open Source under EPL Licnese.
+
 
+
== Description ==
+
XWT is a markup language for declarative application programming. It is a specific solution of using XML grammar for SWT/JFace directly.
+
 
+
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. Unlike most other markup languages, XWT directly represents the instantiation of managed objects.
+
 
+
The benefices of XWT for e4 are following:
+
# More '''human-readable''' and '''light-weight markup''' without ambiguity between properties and child type
+
# '''High Extensible'''
+
# Well defined and complete specification
+
# Mature and Generic Declarative UI solution
+
 
+
=== Examples of XWT ===
+
==== 1. Hello, world ====
+
Here is a simple example.
+
<source lang="xml">
+
<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>
+
</source>
+
 
+
The same UI can be developed in Java corresponding:
+
 
+
<source lang="java">
+
Shell parent = new Shell();
+
parent.setLayout(new FillLayout());
+
Button button = new Button(parent, SWT.NONE);
+
button.setText("Hello, world!");
+
</source>
+
[[Image:XAMl4SWT_HelloWorld.png]]
+
 
+
To load and start a simple application, we use the class XWT:
+
<source lang="java">
+
Shell shell = (Shell) XWT.load(file));
+
shell.pack();
+
shell.open();
+
while (!shell.isDisposed()) {
+
  if (!shell.getDisplay().readAndDispatch()) {
+
shell.getDisplay().sleep();
+
  }
+
}
+
</source>
+
 
+
Or simply
+
 
+
<source lang="java">
+
XWT.open(file));
+
</source>
+
 
+
It is possible to load a UI resource under a Composite:
+
<source lang="java">
+
XWT.load(parent, uri);
+
</source>
+
 
+
To use XWT, your Java project must import at least the following plugins
+
<source lang="java">
+
org.eclipse.swt
+
org.eclipse.jface
+
org.eclipse.e4.xwt
+
org.eclipse.jface.databinding
+
org.eclipse.core.databinding
+
com.ibm.icu
+
</source>
+
 
+
==== 2. Appearance and Event ====
+
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. 
+
<source lang="xml">
+
<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>
+
</source>
+
 
+
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:
+
 
+
<source lang="java">
+
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!");
+
    }
+
}
+
</source>
+
When the button gets selected, the method clickButton is invoked to change the Button text to "Hello, world!".
+
 
+
==== 3. Layout ====
+
<source lang="xml">
+
<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>
+
</source>
+
[[Image:XAMl4SWT_HelloWorld2.png]]
+
 
+
# 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:
+
<source lang="java">
+
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));
+
</source>
+
 
+
==== 4. 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:
+
<source lang="xml">
+
<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>
+
</source>
+
 
+
In the same way, a customized UI component can be used directly:
+
 
+
<source lang="xml">
+
<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>
+
</source>
+
 
+
Where the ui.PersonView is a UI component developed by two files:
+
 
+
XWT file PersonView.xwt
+
<source lang="xml">
+
<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>
+
</source>
+
 
+
Java class PersonView.java
+
<source lang="java">
+
package ui;
+
import org.eclipse.swt.widgets.Composite;
+
 
+
public class PersonView extends Composite {
+
  ...
+
}
+
</source>
+
 
+
==== 5. Data Binding ====
+
The DataBinding engine relies on Eclipse DataBinding component. To enable this feature, your Java project must import at least the following plugins
+
<source lang="java">
+
org.eclipse.swt
+
org.eclipse.jface
+
org.eclipse.e4.xwt
+
org.eclipse.jface.databinding
+
org.eclipse.core.databinding
+
org.eclipse.core.databinding.beans
+
com.ibm.icu
+
</source>
+
 
+
If we bind the text attribute of Label to a property “Name” of a Person, here is the data binding expression:
+
 
+
<source lang="xml">
+
<Label text="{binding path=Name}"/>
+
</source>
+
 
+
It has the same result as following, but the expression is in pure XML:
+
<source lang="xml">
+
<Label>
+
  <Label.text>
+
      <Binding path=”Name”/>
+
  </Label.text>
+
<Label>
+
</source>
+
 
+
The data context of Label should be a person.
+
 
+
==== 6. 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.
+
 
+
<source lang="xml">
+
<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>
+
</source>
+

Latest revision as of 16:40, 23 July 2009

This page is moved to http://wiki.eclipse.org/E4/XWT