12.2. Application-Level Windows

Creating a new application-level window is much like creating a child window (see Section 4.3, “Sub-Windows”), except that the window is added with addWindow() to the application object instead of the main window.

public class WindowTestApplication extends Application {
    public void init() {
        // First create the main window.
        final Window main = new Window ("My Test Application");
        setMainWindow(main);
         
        // Create another application-level window.
        final Window mywindow = new Window("Second Window");
        
        // Manually set the name of the window.
        mywindow.setName("mywindow");
        
        // Add some content to the window.
        mywindow.addComponent(new Label("Has content."));

        // Add the window to the application.
        addWindow(mywindow);
    }
}

This creates the window object that a user can view by opening a URL in a browser. Creating an application-level window object does not open a new browser window automatically to view the object, but if you wish to open one, you have to do it explicitly as shown below. An application-level window has a unique URL, which is based on the application URL and the name of the window given with the setName() method. For example, if the application URL is http://localhost:8080/myapp/ and the window name is mywindow, the URL for the window will be http://localhost:8080/myapp/mywindow/. If the name of a window is not explicitly set with setName(), an automatically generated name will be used. The name can be retrieved with the getName() method and the entire URL with getURL().

There are three typical ways to open a new window: using the open() method of Window class, a Link, or referencing it from HTML or JavaScript code written inside a Label component.

The Window open() method takes as parameters a resource to open and the target name. You can use ExternalResource to open a specific URL, which you get from the window to be opened with the getURL() method.

/* Create a button to open a new window. */
main.addComponent(new Button("Click to open new window",
                  new Button.ClickListener() { 
    public void buttonClick(ClickEvent event) {
        // Open the window.
        main.open(new ExternalResource(mywindow.getURL()),
                  "_new");
    }      
}));

The target name is one of the default HTML target names (_new, _blank, _top, etc.) or a custom target name. How the window is exactly opened depends on the browser. Browsers that support tabbed browsing can open the window in another tab, depending on the browser settings.

Another typical way to open windows is to use a Link component with the window URL as an ExternalResource.

/* Add a link to the second window. */
Link link = new Link("Click to open second window",
                     new ExternalResource(mywindow.getURL()));
link.setTargetName("second");
link.setTargetHeight(300);
link.setTargetWidth(300);
link.setTargetBorder(Link.TARGET_BORDER_DEFAULT);
main.addComponent(link);

Using a Link allows you to specify parameters for the window that opens by clicking on the link. Above, we set the dimensions of the window and specify what window controls the window should contain. The Link.TARGET_BORDER_DEFAULT specifies to use the default, which includes most of the usual window controls, such as the menu, the toolbar, and the status bar.

Another way to allow the user to open a window is to insert the URL in HTML code inside a Label. This allows even more flexibility in specifying how the window should be opened.

// Add the link manually inside a Label.
main.addComponent(
    new Label("Second window: <a href='" + mywindow.getURL()
              + "' target='second'>click to open</a>",
              Label.CONTENT_XHTML));
main.addComponent(
    new Label("The second window can be accessed through URL: "
              + mywindow.getURL()));

When an application-level window is closed in the browser the close() method is normally called just like for a child window and the Window object is purged from the application. However, there are situations where close() might not be called. See Section 12.2.4, “Closing Windows” for more information.

public class WindowTestApplication extends Application {
    ...

    @Override
    public Window getWindow(String name) {
        // If a dynamically created window is requested, but
        // it does not exist yet, create it.
        if (name.startsWith("planet-") &&
              super.getWindow(name) == null) {
            String planetName =
                    name.substring("planet-".length());

            // Create the window object.
            Window newWindow =
                    new Window("Window about " + planetName);
            
            // DANGEROUS: Set the name explicitly. Otherwise,
            // an automatically generated name is used, which
            // is usually safer.
            newWindow.setName(name);

            // Put some content in it.
            newWindow.addComponent(
                new Label("This window contains details about " +
                          planetName + "."));
            
            // Add it to the application as a regular
            // application-level window.
            addWindow(newWindow);
            
            return newWindow;
        }

        // Otherwise the Application object manages existing
        // windows by their name.
        return super.getWindow(name);
    }

The window name must be a unique indentifier for each Window object instance. If you use setName() to set the window name explicitly, as we did above, any browser window that has the same URL (within the same browser) would open the same window object. This is dangerous and generally not recommended, because the browser windows would share the same window object. Opening two windows with the same static name would immediately lead to a synchronization error, as is shown in Figure 12.1, “Synchronization Error Between Windows with the Same Name” below. (While also the window captions are same, they are irrelevant for this problem.)

Figure 12.1. Synchronization Error Between Windows with the Same Name

Figure 12.2, “A Dynamically Created Window” shows a dynamically created application-level window with the URL shown in the address bar. The URL for the application is here http://localhost:8080/book-examples/windowexample/, including the application context, application path. The dynamically created window's name is planet-mars.

Figure 12.2. A Dynamically Created Window

The application knows the windows it already has and can return them after the creation. The application also handles closing and destruction of application-level window objects, as discussed in Section 12.2.4, “Closing Windows”.

Such dynamic windows could be opened as in the following example:

public void init() {
    final Window main = new Window("Window Test");
    setMainWindow(main);

    // Have some IDs for the dynamically creatable windows.
    final String[] items = new String[] { "mercury", "venus",
            "earth", "mars", "jupiter", "saturn", "uranus",
            "neptune" };
    
    // Create a list of links to each of the available window.
    for (int i = 0; i < items.length; i++) {
        // Create a URL for the window.
        String windowUrl = getURL() + "planet-" + items[i];
        
        // Create a link to the window URL. Using the 
        // item ID for the target also opens it in a new
        // browser window (or tab) unique to the window name.
        main.addComponent(
            new Link("Open window about " + items[i],
                     new ExternalResource(windowUrl),
                     items[i], -1, -1, Window.BORDER_DEFAULT));
    }
}

Figure 12.3. Opening Windows

newWindow.addListener(new Window.CloseListener() {
    @Override
    public void windowClose(CloseEvent e) {
        // Do something.
        System.out.println(e.getWindow().getName() +
                           " was closed");

        // Add a text to the main window about closing.
        // (This does not update the main window.)
        getMainWindow().addComponent(
            new Label("Window '" + e.getWindow().getName() +
                      "' was closed."));
    }
});

Notice that the change to the server-side state of the main window (or another application-level window) does not refresh the window in the browser, so the change will be unseen until user interaction or polling refreshes the window. This problem and its dangers are discussed in Section 12.2.5, “Caveats in Using Multiple Windows” below.

The close event does not occur if the browser crashes or the connection is otherwise severed violently. In such a situation, the window object will be left hanging, which could become a resource problem if you allow the users to open many such application-level windows. The positive side is that the user can reconnect to the window using the window URL.