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 an 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 by its name 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 Finding

In XWT XML, an element also can be found by its name. It mostly used in control binding. Control binding is used to establish a connection among two or more UI elements.

<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 above example, it start to search from top="{Binding ElementName=Button1}, it try to find the element named Button1 in the current NamedScope, if not found, the search will proceed in its parent NamedScope. If the element is exist in the tree structure and it has the correct settings. the top property of the second button synchronized with Button1, Or the code will show error.