6.8. TabSheet

The TabSheet is a multicomponent container that allows switching between the components with "tabs". The tabs are organized as a tab bar at the top of the tab sheet. Clicking on a tab opens its contained component in the main display area of the layout.

New tabs can be added simply with the addComponent() method, but doing so leaves them without a caption. You can set the caption with setTabCaption() or simply use the addTab() method to create tabs and give them a caption. In addition to a caption, tabs can contain an icon, which you can define either in the addTab() call or set later with setTabIcon().

The following example demonstrates the creation of a simple tab sheet, where each the tabs shows a different Label component. The tabs have an icon, which are loaded as Java class loader resources from the WAR package of the application.

final TabSheet tabsheet = new TabSheet();
tabsheet.addStyleName("tabsheetexample");

// Make the tabsheet to shrink to fit the contents.
tabsheet.setSizeUndefined();

tabsheet.addTab(new Label("Contents of the first tab"),
                "First Tab",
                new ClassResource("images/Mercury_small.png", this));
tabsheet.addTab(new Label("Contents of the second tab"),
                "Second Tab",
                new ClassResource("images/Venus_small.png", this));
tabsheet.addTab(new Label("Contents of the third tab"),
                "Third tab",
                new ClassResource("images/Earth_small.png", this));

Figure 6.8. A Simple TabSheet Layout

The hideTabs() method allows hiding the tab bar entirely. This can be useful in tabbed document interfaces (TDI) when there is only one tab. An individual tab can be made invisible by making its component invisible with setVisible(false). A tab can be disabled by disabling its component with setEnabled(false). A tab can be selected programmatically with setSelectedTab().

Clicking on a tab selects it. This fires a TabSheet.SelectedTabChangeEvent, which can be handled with the TabSheet.SelectedTabChangeListener. The source component of the event, which you can retrieve with getSource() method of the event, will be the TabSheet component. You can find out the currently selected component with getSelectedTab().

The example below demonstrates handling TabSheet related events and enabling and disabling tabs. The sort of logic used in the example is useful in sequential user interfaces, often called wizards, where the user goes through the tabs one by one, but can return back if needed.

import com.itmill.toolkit.ui.*;
import com.itmill.toolkit.ui.Button.ClickEvent;
import com.itmill.toolkit.ui.TabSheet.SelectedTabChangeEvent;

public class TabSheetExample extends CustomComponent
        implements Button.ClickListener, TabSheet.SelectedTabChangeListener {
    TabSheet tabsheet = new TabSheet();
    Button tab1 = new Button("Push this button");
    Label  tab2 = new Label("Contents of Second Tab");
    Label  tab3 = new Label("Contents of Third Tab");
    
    TabSheetExample () {
        setCompositionRoot (tabsheet);

        /* Listen for changes in tab selection. */
        tabsheet.addListener(this);

        /* First tab contains a button, for which we listen button click events. */
        tab1.addListener(this);
        tabsheet.addTab(tab1, "First Tab", null);

        /* A tab that is initially invisible. */
        tab2.setVisible(false);
        tabsheet.addTab(tab2, "Second Tab", null);
        
        /* A tab that is initially disabled. */
        tab3.setEnabled(false);
        tabsheet.addTab(tab3, "Third tab", null);
    }

    public void buttonClick(ClickEvent event) {
        /* Enable the invisible and disabled tabs. */
        tab2.setVisible(true);
        tab3.setEnabled(true);
        
        /* Change selection automatically to second tab. */
        tabsheet.setSelectedTab(tab2);
    }

    public void selectedTabChange(SelectedTabChangeEvent event) {
        TabSheet source = event.getTabSheet();
        if (source == tabsheet) {
            /* If the first tab was selected. */
            if (source.getSelectedTab() == tab1) {
                tab2.setVisible(false);
                tab3.setEnabled(false);
            }
        }
    }
}

Figure 6.9. A TabSheet with Hidden and Disabled Tabs

.i-tabsheet {}
.i-tabsheet-tabs {}
.i-tabsheet-content {}
.i-tabsheet-deco {}
.i-tabsheet-tabcontainer {}
.i-tabsheet-tabsheetpanel {}
.i-tabsheet-hidetabs {}

.i-tabsheet-scroller {}
.i-tabsheet-scrollerPrev {}
.i-tabsheet-scrollerNext {}
.i-tabsheet-scrollerPrev-disabled{}
.i-tabsheet-scrollerNext-disabled{}

.i-tabsheet-tabitem {}
.i-tabsheet-tabitem-selected {}
.i-tabsheet-tabitemcell {}
.i-tabsheet-tabitemcell-first {}

.i-tabsheet-tabs td {}
.i-tabsheet-spacertd {}