# Markup language

Markup languages are designed for the processing, definition and presentation of text. XWT provides an Extensible UI Markup Language for declarative Eclipse application programming.

- A Declarative language with Flow Control Support
- XWT Object Elements
- Setting Properties
- Reference Values and Markup Extensions
- Case and Whitespace
- XWT Root Elements and XML Namespaces
- Events and XWT Code-behind

### A Declarative language with Flow Control Support

XWT simplifies creating a UI for Java programming. You can create visible UI elements in the XWT declarative 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, and does not really suggest a model for flow control.

The following XWT example shows how markup is necessary to create a button as part of a UI.

    <Shell.layout>
        <GridLayout numColumns="1" />
    </Shell.layout>
    <Button text="Hello" />

### XWT Object Elements

XWT has a set of rules that map object elements into classes or structures, attributes into properties or events, and XML namespaces to Java packages.

The preceding example specified two object elements: <GridLayout /> and <Button />. The string GridLayout and Button each map to the name of a class that is defined by XWT and is part of the XWT assemblies. When you specify an object element tag, you create an instruction for XWT processing to create a new instance of the named class when your XWT page is loaded. Each instance is created by calling the default constructor of the underlying class or structure and storing the result. To be usable as an object element in XWT, the class or structure must expose a public default (parameterless) constructor.

### Setting Properties

Properties in XWT are set by setting properties on an object element, using a variety of possible syntaxes. Which syntaxes can be used for a given property will vary, based on the characteristics of the property that you are setting.

By setting values of properties, you add features or characteristics to object element. The initial state of the underlying object instance for an object element is based on the default constructor behavior. Typically, your application will use something other than a completely default instance of any given object.

Attribute Syntax

In XWT, properties can often be expressed as attributes. Attribute syntax is the most streamlined property setting syntax and will be the most intuitive syntax to use for developers that have used markup languages in the past. For example, the following markup creates a button that with push style, as well as display text specified as test.

    <Button x:style="PUSH" text="Hello, world!" />

Property Element Syntax

For some properties of an object element, attribute syntax is not possible, because the object or information necessary to provide the property value cannot be adequately expressed as a simple string. For these cases, a different syntax known as property element syntax can be used. Property element syntax sets the referenced property of the containing element with the content of the tag. Generally, the content is an object of the type that the property takes as its value. The syntax for property element itself is <TypeName.Property>. After specifying content, you must close the property element with a closing tag just like any other element (with syntax </TypeName.Property>). For properties where both attribute and property element syntax are supported, the two syntaxes generally have the same result, although subtleties such as whitespace handling can vary slightly between syntaxes. The following example is using property element syntax for text properties of the Button.

    <Button>
        <Button.text>
        This is a Button
        </Button.text>
    </Button>

### Reference Values and Markup Extensions

Markup extensions are an XWT concept. In attribute syntax, curly braces ({ and }) indicate a markup extension usage. This usage directs the XWT processing to escape from the general treatment of attribute values are either a literal string or directly string-convertible value.

When properties take a reference type value, these properties will often require either property element syntax (which always creates a new instance) or an object reference through a markup extension. A markup extension usage can potentially return an existing instance, and thus can be more versatile or might incur less object overhead.

When a markup extension is used to provide an attribute value, the attribute value should instead be provided by the logic within the backing class for the relevant markup extension. The most common markup extensions used in XWT application programming are Binding, used for data binding expressions and the resource reference StaticResource and DynamicResource. By using markup extension, you can use attribute syntax to provide reference values for properties even if that the property does not support an attribute syntax for direct object instantiation, or enable specific behavior that defers the general behavior of the requirement that XAML properties must be filled by values of the property's type.

For instance, the following example sets the value of text property using attribute syntax. The text binds a Person class.

    <Shell
        ...
        DataContext="{StaticResource myData}">
        ...
        <x:Shell.Resources>
            <y:Person x:Key="myData"/>
        </x:Shell.Resources>

        <Text x:style="BORDER" text="{Binding Path=name}">
            <Text.layoutData>
                <GridData horizontalAlignment="FILL"
                    grabExcessHorizontalSpace="true"/>
            </Text.layoutData>
        </Text>
        ...
    </Shell>

### Case and Whitespace

XWT is in general case sensitive. Object elements and property elements must all be specified by using the proper case when compared by name to the underlying type in programming language, or to a member of a type. There is one exception for attribute name. The first letter and only the first letter of attribute name is not case-sensitive.

The values for attributes are not always case sensitive. Case sensitivity for values will depend on the type converter behavior associated with the property that takes the value, or the property value type. For instance, properties that take Boolean type can take either true or True as equivalent values, but only because the default string type conversion for Boolean already permits these as equivalents.

XWT processors and serializers will ignore or drop all non-significant whitespace, and will normalize any significant whitespace. This behavior is generally only of consequence when you specify strings within XWT content properties. In simplest terms, XWT converts space, line feed and tab characters into spaces and then preserves one space if found at either end of a contiguous string.

### XWT Root Elements and XML Namespaces

An XWT file must have only one root element, in order to be both a well-formed XML file and a valid XWT file. Typically you should choose an element that is part of the application model. The following example shows the root element of a typical XWT file with the root element Composite.

    <Composite xmlns="http://www.eclipse.org/xwt/presentation"
        xmlns:x="http://www.eclipse.org/xwt">
        ...
    </Composite>

The root element also contains the attributes xmlns and xmlns:x. These attributes indicate to an XWT processor which XML namespaces contain the element definitions for elements that the markup will reference. The xmlns attribute specifically indicates the default XML namespace. Within the default XML namespace, object elements in the markup can be specified without a prefix. The default XML namespace is mapped to the namespace "http://www.eclipse.org/xwt/presentation". The xmlns:x attribute indicates an additional XML namespace, which maps the XWT language namespace "http://www.eclipse.org/xwt". Required language components defined by the XWT specification are prefixed by x: when referenced in the markup of a file with this mapping.

The x:Prefix

In the previous root element example, the prefix x: was used to map the XWT XML namespace "http://www.eclipse.org/xwt". This x: prefix will be used to map the XWT XML namespace in the templates for projects. The x:prefix XML namespace contain several programming constructs that you will use quite frequently in your XWT. The following is a listing of the most common x:prefix namespace programming constructs you will use:

- x:Key: Sets a unique key for each resource in a DataContext.
- x:Class: Specifies the CLR namespace and class name for the class that provides code-behind for an XWT page. You must have such a class to support code-behind, and it is for this reason that you almost always see x: mapped, even if there are no resources.
- x:Name: Specifies a object name for the instance.
- x:Null: null in Java.
- x:Static: Enables a value reference that gets a static value that is not otherwise an XWT-compatible property.
- x:Type: Constructs a Type reference based on a type name.
- x:Array: Provides general support for arrays of objects in XWT.
- x:Style: Specifies the type of a instance.

### Events and XWT Code-behind

Most XWT applications consist of both markup and code-behind. Within a project, the XWT is written as .xwt file and a synchronized java class is used to write a code-behind file. When an XWT file is loaded, the location of the XWT code-behind file for each XWT page is identified by specifying a namespace and class as the x:Class attribute of the root element of the XWT page.

In the examples so far, you have seen several buttons, but none of these buttons had any logical behavior associated with them yet. The primary application-level mechanism for adding a behavior for an object element is to use an existing event of the element class, and to write a specific handler for that event that is invoked when that event is raised at run time. The event name and the name of the handler to use are specified in the markup, whereas the code that implements your handler is defined in the code-behind.

XWT:

    <Shell xmlns="http://www.eclipse.org/xwt/presentation"
        xmlns:x="http://www.eclipse.org/xwt"
        x:Class="org.eclipse.e4.xwt.tests.events.ButtonHandler">
        <Shell.layout>
            <GridLayout numColumns="2"/>
        </Shell.layout>
        <Button text="Hello, world" SelectionEvent="selection"/>
    </Shell>

Java:

    protected void selection(Event event) {
        Button button = (Button) event.widget;
        button.setText("OK");
    }

Event Attribute Syntax

When you specify behavior through events in markup, you typically use attribute syntax to attach handlers. The object element where the event attribute is specified becomes the instance that listens for the event and calls the handler. The name of the specific event you want to handle is the attribute name. The attribute value is the method name of the handler you will define. You must then provide the handler implementation in code-behind, with the handler being based on the delegate for that event.