Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "E4/DeclarativeUI/XWT"

(New page: == Name of Technology == XWT == Purpose == Adopt a direct mapping XML to SWT/JFace with the support of JFace DataBinding == Contact == [mailto:yves.yang@soyatec.com Yves YANG] == Commi...)
 
(Replacing page with 'This page is moved to [http://wiki.eclipse.org/E4/XWT http://wiki.eclipse.org/E4/XWT]')
 
(17 intermediate revisions by 2 users 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
+
 
+
== 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 creating a UI programming model. You can create visible UI elements in the declarative XML markup, and then separate the UI definition from the run-time logic by using code-behind files. The ability to mix code with markup in XWT is important because XML by itself is declarative. 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. This general design principle enables simplified code and debugging access for objects that are created in XWT.
+
 
+
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 = XWT.load(file).getShell();
+
shell.pack();
+
shell.open();
+
while (!shell.isDisposed()) {
+
  if (!shell.getDisplay().readAndDispatch()) {
+
shell.getDisplay().sleep();
+
  }
+
}
+
</source>
+
 
+
It is possible to load a UI resource under a Composite:
+
<source lang="java">
+
XWT.load(parent, uri);
+
</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.
+
 
+
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

Back to the top