Naming and Element finding

Naming a UI component is used to find an element by a unique name in UI structure tree. This concept is used both in Java class by programming and in XML via Control Binding concept.

The name must be in unique in a scope, named as "Named scope". The named scope corresponds with a XWT resource file.

Finding in Java

XWT uses x:Name property or Name property to name a component. This section will show how to name an element and how to find an element in Java class.

In the example below, we will create a Label named Message and a Button.

XAML:

<Shell xmlns="http://www.eclipse.org/xwt/presentation"
    xmlns:x="http://www.eclipse.org/xwt"
    x:Class="org.eclipse.e4.xwt.tests.name.Name_x"
    text="NameT test">
    <Shell.layout>
        <GridLayout numColumns="2" />
    </Shell.layout>
    <Label Name="Message" />
    <Button SelectionEvent="handleButton" Text="Click Here" />
</Shell>

Consider the example above, the Label gets a name "Message", and set the contents of the button with string "Click Here". Then we add an event handling here by SelectionEvent property and named the event "handleButton". In the rendered window, when we click the button, the handleButton tries to find the Label. If it works, dialog "Name works" will pop-up. Otherwise, an error dialog "Label message is not found" will open instead. Please see the Java code below.

Java:

protected void handleButton(Event event) {
    Label message = (Label) XWT.findElementByName(event.widget, "Message");
    if (message == null) {
        MessageDialog.openError(XWT.findShell(event.widget), "Test Name", "Label message is not found");
    } else {
        MessageDialog.openInformation(XWT.findShell(event.widget), "Test Name", "Name works.");
    }
}

The first argument of findElementByName() indicates the start point of search. Precisely, the search starts with its NamedScope. If the name is not find in the current NamedScope, the search will proceed in its parent NamedScope. The "null" will be returned if the name is not found in the entire tree structure.

Element Binding

The element also can be found via Control Binding between UI elements. It mostly used in an element binding. Element binding is a connection of two UI element. Please see the example below.

<Shell xmlns="http://www.eclipse.org/xwt/presentation"
    xmlns:x="http://www.eclipse.org/xwt"
    x:Class="org.eclipse.e4.xwt.tests.layout.FormLayout_Test">
    <Shell.layout>
        <FormLayout />
    </Shell.layout>
    <Group text="layout">
        <Group.layout>
            <FormLayout />
        </Group.layout>
        <Group.layoutData>
            <GridData horizontalAlignment="FILL" verticalAlignment="FILL">
            </GridData>
        </Group.layoutData>
        <Button x:Name="Button1" text="button1">
            <Button.layout>
                <FormData top="10, 10" left="0, 10" bottom="30, 0" right="40, 0" />
            </Button.layout>
        </Button>
        <Button text="button2">
            <Button.layout>
                <FormData top="{Binding ElementName=Button1}, 10" left="0, 0"
            bottom="40, 0" right="40, 0" />
            </Button.layout>
        </Button>
    </Group>
</Shell>

Consider the example above, we name the first button "Button1" by x:Name property. Then we keep the top property of the second button synchronized with the first button. Here using a binding object to establish a binding and ElementName property to specify the source object.