Understanding Layout

Panels in GWT are much like their layout counterparts in other user interface libraries. The main difference lies in the fact that GWT panels use HTML elements such as DIV and TABLE to layout their child widgets.

RootPanel

The first panel you're likely to encounter is the RootPanel. This panel is always at the top of the containment hierarchy. The default RootPanel wraps the HTML document's body, and is obtained by calling RootPanel.get(). If you need to get a root panel wrapping another element in the HTML document, you can do so using RootPanel.get(String).

CellPanel

CellPanel is the abstract base class for DockPanel, HorizontalPanel, and VerticalPanel. What these panels all have in common is that they position their child widgets within logical "cells". Thus, a child widget can be aligned within the cell that contains it, using setCellHorizontalAlignment() and setCellVerticalAlignment(). CellPanels also allow you to set the size of the cells themselves (relative to the panel as a whole) using setCellWidth() and setCellHeight().

Below is an example of using a HorizontalPanel from the Showcase sample application:

    // Create a Horizontal Panel
    HorizontalPanel hPanel = new HorizontalPanel();

    // Leave some room between the widgets
    hPanel.setSpacing(5); 

    // Add some content to the panel
    for (int i = 1; i < 5; i++) {
      hPanel.add(new Button("Button " + i));
    }

Each new Button widget is added to the right hand side of the panel, creating a horizontal row of widgets. The VerticalPanel works the same way, but adds new widgets to the bottom of the panel and lays them out vertically.

A more powerful layout mechanism is provided by the DockPanel. A DockPanel aligns its components using compass directions, where north points up on the screen. Below is an example of using a DockPanel from the Showcase sample application:

    DockPanel dock = new DockPanel();

    // Allow 4 pixels of spacing between each cell
    dock.setSpacing(4);

    /* Center each component horizontally within each cell
     * for each component added after this call.
     * A shortcut to calling dock.setCellHorizontalAlignment()
     * for each cell.
     */
    dock.setHorizontalAlignment(DockPanel.ALIGN_CENTER);

    // Add text widgets all around
    dock.add(new HTML("This is the <i>first</i> north component"),
        DockPanel.NORTH);
    dock.add(new HTML("This is the <i>first</i> south component"),
        DockPanel.SOUTH);
    dock.add(new HTML("This is the east component"), DockPanel.EAST);
    dock.add(new HTML("This is the west component"), DockPanel.WEST);
    dock.add(new HTML("This is the <i>second</i> north component"),
        DockPanel.NORTH);
    dock.add(new HTML("This is the <i>second</i> south component"),
        DockPanel.SOUTH);

    // Add scrollable text in the center
    HTML contents = new HTML("This is a <code>ScrollPanel</code> contained at "
        + "the center of a <code>DockPanel</code>.  "
        + "By putting some fairly large contents "
        + "in the middle and setting its size explicitly, it becomes a "
        + "scrollable area within the page, but without requiring the use of "
        + "an IFRAME.<br><br>"
        + "Here's quite a bit more meaningless text that will serve primarily "
        + "to make this thing scroll off the bottom of its visible area.  "
        + "Otherwise, you might have to make it really, really small in order "
        + "to see the nifty scroll bars!");
    ScrollPanel scroller = new ScrollPanel(contents);
    scroller.setSize("400px", "100px");
    dock.add(scroller, DockPanel.CENTER);

As you can see in the screenshot below, the order of adding components to the DocPanel is important if you add more than one component to the same direction. The first component added will be closest to the edge. The next component added will nest toward the inside of the panel.

Tab Panel

The TabPanel displays a row of clickable tabs. Each tab is associated with a panel which can contain a sub panel or arbitrary HTML which is exposed in a main viewing area when the tab is selected. The main viewing area is implemented with a DeckPanel. An example of using a Tab Panel follows:

    // Create a tab panel
    TabPanel tabPanel = new TabPanel();

    // Set the width to 400 pixels
    tabPanel.setWidth("400px");

    // Add a home tab
    HTML homeText = new HTML("Click one the tabs to see more content.");
    tabPanel.add(homeText, "Home");

    // Add a tab with an image
    VerticalPanel vPanel = new VerticalPanel();
    vPanel.add(Showcase.images.gwtLogo().createImage());
    tabPanel.add(vPanel, "GWT Logo");

    // Add a third tab
    HTML moreInfo = new HTML("Tabs are highly customizable using CSS");
    tabPanel.add(moreInfo, "More Info");

    // Make the first tab selected and the tab's content visible
    tabPanel.selectTab(0);

The screenshot below shows the TabPanel focused on the first tab. As you can see from the code example, you can add HTML or other panels to be displayed as the content of the tab. You might also notice that the widget looks different than the default Tab Panel. The Showcase demo uses CSS Stylesheets to change the appearance of the panel.

Horizontal and Vertical Split panels

The HorizontalSplitPanel and VerticalSplitPanel arrange two widgets in a single row or column and allow the user to interactively change the proportion of the width dedicated to each of the two widgets. Widgets contained within the split panels will be automatically decorated with scrollbars when necessary.

    // Create a Vertical Split Panel
    VerticalSplitPanel vSplit = new VerticalSplitPanel();

    // Set the bounding box in pixels
    vSplit.setSize("500px", "350px");

    /* Set the position of the handle 30% from the top of the
     * panel.
     */
    vSplit.setSplitPosition("30%");

    // Add some content
    String randomText = "This is some text to show how the contents on either "
        + "side of the splitter flow.   "
        + "This is some text to show how the contents on either "
        + "side of the splitter flow.   "
        + "This is some text to show how the contents on either "
        + "side of the splitter flow.   ";
    vSplit.setTopWidget(new HTML(randomText));
    vSplit.setBottomWidget(new HTML(randomText));

By manipulating the handle in the middle of the panel, the user can expose more of the upper or lower portion of the panel, as shown in the screenshot below.

The HorizontalSplitPanel works in the same way, only aligns its children horizontally.

Other Panels

Other panels include

See the Widget Gallery for screenshots or diagrams for these panels.

Sizes and Measures

It is possible to set the size of a widget explicitly using setWidth(), setHeight(), and setSize(). The arguments to these methods are strings, rather than integers, because they accept any valid CSS measurements, such as pixels (128px), centimeters (3cm), and percentage (100%).