Event Handling

While WTKX is used to declare the structure of an application, the application's behavior is defined in code (either Java or a JVM-compatible scripting language). Most of this logic is executed in response to an "event" triggered by some external source, such as user input or the completion of an asynchronous operation running in a background thread.

In general, a Pivot application will load its user interface and wire up event handlers in the startup() method of the main application class. This method, along with the shutdown(), suspend(), and resume() methods, is defined by the Application interface, which all Pivot applications must implement.

Loading the UI

The Application interface in the Stock Tracker demo is implemented by the StockTracker class. The code in this file is referred to throughout the course of this section. A snippet of code from StockTracker's startup() method is shown below:

// Set the locale
String language = properties.get(LANGUAGE_PROPERTY_NAME);
if (language != null) {
    Locale.setDefault(new Locale(language));
}

// Load and bind to the WTKX source
Resources resources = new Resources(this);
WTKXSerializer wtkxSerializer = new WTKXSerializer(resources);
window = (Window)wtkxSerializer.readObject(this, "stocktracker.wtkx");
wtkxSerializer.bind(this, StockTracker.class);

This code does the following:

• Retrieves the "langauge" argument that was provided to the application context when it was created - for desktop applications, this is a command-line argument; in the browser, it is either passed via an applet parameter

• Sets the default locale to an instance corresponding to the language argument

• Loads the application resources

• Creates an instance of WTKXSerializer and loads the WTKX source

Finally, the code calls the bind() method on the serializer, which associates annotated member variables with corresponding IDs in the WTKX file:

@WTKX private TableView stocksTableView;
@WTKX private TextInput symbolTextInput;
@WTKX private Button addSymbolButton;
@WTKX private Button removeSymbolsButton;
...

These annotations eliminate much of the boilerplate code required when loading WTKX contents manually via an instance of WTKXSerializer. However, since they rely on reflection code that may need to set private member variables, they can only be used by trusted code, such as a locally installed application or a signed applet or Web Start application.

Adding Event Listeners

At this point, the entire UI has been created, but it is not yet visible. Even if it was, it wouldn't do much, since no event handlers have been added. The next thing startup() does is add a number of event handlers:

stocksTableView.getTableViewSelectionListeners().add(new TableViewSelectionListener.Adapter() {
    public void selectedRangesChanged(TableView tableView, Sequence<Span> previousSelectedRanges) {
        refreshDetail();
    }
});
...

addSymbolButton.getButtonPressListeners().add(new ButtonPressListener() {
    public void buttonPressed(Button button) {
        addSymbol();
    }
});
...

A caller signals its interest in a particular event by implementing an interface that defines an event handler method and adding itself as an event lister on the event source. In the example above, two event handlers are created: a selection change listener on the stock quote table view and a button press listener on the "add symbol" button. Some listener interfaces, such as those shown here, define only a single event handler method, but others define more than one and serve as a grouping of related events. Interfaces with multiple handler methods generally define an inner Adapter class that can be used to simplify subclassing, as shown above.

Note that, though these handlers are implemented as anonymous inner classes, this is not required - any class that implements the appropriate listener interface can register as a listener. It is also possible to define listeners in script within the WTKX file itself; this is discussed in more detail in the Scripting section.

Displaying the Content

Finally, the window loaded from the WTKX files is opened, making the application visible and allowing the user to begin interacting with it (note that the window's "maximized" property is set to "true" in the WTKX file so that, when opened, the window will be sized to fit the entire display area):

window.open();

refreshTable();

ApplicationContext.setInterval(new Runnable() {
    public void run() {
        refreshTable();
    }
}, REFRESH_INTERVAL);

symbolTextInput.requestFocus();

The code then calls refreshTable() to load the stock quote data and sets a timer interval to reload the data every 15 seconds. Finally, it sets the focus to the symbol text input, so a user can easily add a new stock to track.

Next: Web Queries