com.google.gwt.user.client.ui

## Class TabBar

- java.lang.Object
- - com.google.gwt.user.client.ui.UIObject
  - - com.google.gwt.user.client.ui.Widget
    - - com.google.gwt.user.client.ui.Composite
      - - com.google.gwt.user.client.ui.TabBar

- All Implemented Interfaces:
    HasAttachHandlers, HasBeforeSelectionHandlers<java.lang.Integer>, HasSelectionHandlers<java.lang.Integer>, HasHandlers, EventListener, ClickListener, HasVisibility, IsRenderable, IsWidget, KeyboardListener, SourcesTabEvents
  Direct Known Subclasses:
    DecoratedTabBar

      public class TabBar
      extends Composite
      implements SourcesTabEvents, HasBeforeSelectionHandlers<java.lang.Integer>, HasSelectionHandlers<java.lang.Integer>, ClickListener, KeyboardListener

  A horizontal bar of folder-style tabs, most commonly used as part of a `TabPanel`.

  ### CSS Style Rules

  - .gwt-TabBar { the tab bar itself }
  - .gwt-TabBar .gwt-TabBarFirst { the left edge of the bar }
  - .gwt-TabBar .gwt-TabBarFirst-wrapper { table cell around the left edge }
  - .gwt-TabBar .gwt-TabBarRest { the right edge of the bar }
  - .gwt-TabBar .gwt-TabBarRest-wrapper { table cell around the right edge }
  - .gwt-TabBar .gwt-TabBarItem { unselected tabs }
  - .gwt-TabBar .gwt-TabBarItem-wrapper { table cell around tab }
  - .gwt-TabBar .gwt-TabBarItem-selected { additional style for selected

    ### Example

    >     public class TabBarExample implements EntryPoint {

    >       public void onModuleLoad() {
    >         // Create a tab bar with three items.
    >         TabBar bar = new TabBar();
    >         bar.addTab("foo");
    >         bar.addTab("bar");
    >         bar.addTab("baz");

    >         // Hook up a tab listener to do something when the user selects a tab.
    >         bar.addSelectionHandler(new SelectionHandler<Integer>() {
    >           public void onSelection(SelectionEvent<Integer> event) {
    >             // Let the user know what they just did.
    >             Window.alert("You clicked tab " + event.getSelectedItem());
    >           }
    >         });

    >         // Just for fun, let's disallow selection of 'bar'.
    >         bar.addBeforeSelectionHandler(new BeforeSelectionHandler<Integer>() {
    >           public void onBeforeSelection(BeforeSelectionEvent<Integer> event) {
    >             if (event.getItem().intValue() == 1) {
    >               event.cancel();
    >             }
    >           }
    >         });

    >         // Add it to the root panel.
    >         RootPanel.get().add(bar);
    >       }
    >     }

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `TabBar.Tab` Set of characteristic interfaces supported by `TabBar` tabs.

    - ### Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.UIObject

      `UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled`

  - ### Field Summary

    - ### Fields inherited from class com.google.gwt.user.client.ui.Widget

      `eventsToSink`

    - ### Fields inherited from class com.google.gwt.user.client.ui.UIObject

      `DEBUG_ID_PREFIX, MISSING_ELEMENT_ERROR, SETELEMENT_TWICE_ERROR`

    - ### Fields inherited from interface com.google.gwt.user.client.ui.KeyboardListener

      `KEY_ALT, KEY_BACKSPACE, KEY_CTRL, KEY_DELETE, KEY_DOWN, KEY_END, KEY_ENTER, KEY_ESCAPE, KEY_HOME, KEY_LEFT, KEY_PAGEDOWN, KEY_PAGEUP, KEY_RIGHT, KEY_SHIFT, KEY_TAB, KEY_UP, MODIFIER_ALT, MODIFIER_CTRL, MODIFIER_META, MODIFIER_SHIFT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TabBar()` Creates an empty tab bar.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `HandlerRegistration` | `addBeforeSelectionHandler(BeforeSelectionHandler<java.lang.Integer> handler)` Adds a `BeforeSelectionEvent` handler.
    `HandlerRegistration` | `addSelectionHandler(SelectionHandler<java.lang.Integer> handler)` Adds a `SelectionEvent` handler.
    `void` | `addTab(SafeHtml html)` Adds a new tab with the specified text.
    `void` | `addTab(java.lang.String text)` Adds a new tab with the specified text.
    `void` | `addTab(java.lang.String text, boolean asHTML)` Adds a new tab with the specified text.
    `void` | `addTab(Widget widget)` Adds a new tab with the specified widget.
    `void` | `addTabListener(TabListener listener)` Deprecated. Use `addBeforeSelectionHandler(BeforeSelectionHandler)` and `addSelectionHandler(SelectionHandler)` instead
    `protected SimplePanel` | `createTabTextWrapper()` Create a `SimplePanel` that will wrap the contents in a tab.
    `int` | `getSelectedTab()` Gets the tab that is currently selected.
    `TabBar.Tab` | `getTab(int index)` Gets the given tab.
    `int` | `getTabCount()` Gets the number of tabs present.
    `java.lang.String` | `getTabHTML(int index)` Gets the specified tab's HTML.
    `void` | `insertTab(SafeHtml html, int beforeIndex)` Inserts a new tab at the specified index.
    `void` | `insertTab(java.lang.String text, boolean asHTML, int beforeIndex)` Inserts a new tab at the specified index.
    `void` | `insertTab(java.lang.String text, int beforeIndex)` Inserts a new tab at the specified index.
    `void` | `insertTab(Widget widget, int beforeIndex)` Inserts a new tab at the specified index.
    `protected void` | `insertTabWidget(Widget widget, int beforeIndex)` Inserts a new tab at the specified index.
    `boolean` | `isTabEnabled(int index)` Check if a tab is enabled or disabled.
    `void` | `onClick(Widget sender)` Deprecated. add a `BeforeSelectionHandler` instead. Alternatively, if you need to access to the individual tabs, add a click handler to each `TabBar.Tab` element instead.
    `protected void` | `onEnsureDebugId(java.lang.String baseID)` Affected Elements: -tab# = The element containing the contents of the tab. -tab-wrapper# = The cell containing the tab at the index.
    `void` | `onKeyDown(Widget sender, char keyCode, int modifiers)` Deprecated. add a key down handler to the individual `TabBar.Tab` objects instead.
    `void` | `onKeyPress(Widget sender, char keyCode, int modifiers)` Deprecated. this method has been doing nothing for the entire last release, if what you wanted to do was to listen to key press events on tabs, add the key press handler to the individual tab wrappers instead.
    `void` | `onKeyUp(Widget sender, char keyCode, int modifiers)` Deprecated. this method has been doing nothing for the entire last release, if what you wanted to do was to listen to key up events on tabs, add the key up handler to the individual tab wrappers instead.
    `void` | `removeTab(int index)` Removes the tab at the specified index.
    `void` | `removeTabListener(TabListener listener)` Deprecated. Instead use the `HandlerRegistration.removeHandler()` call on the object returned by an add*Handler method
    `boolean` | `selectTab(int index)` Programmatically selects the specified tab and fires events.
    `boolean` | `selectTab(int index, boolean fireEvents)` Programmatically selects the specified tab.
    `void` | `setTabEnabled(int index, boolean enabled)` Enable or disable a tab.
    `void` | `setTabHTML(int index, SafeHtml html)` Sets a tab's contents via safe html.
    `void` | `setTabHTML(int index, java.lang.String html)` Sets a tab's contents via HTML.
    `void` | `setTabText(int index, java.lang.String text)` Sets a tab's text contents.

    - ### Methods inherited from class com.google.gwt.user.client.ui.Composite

      `claimElement, getWidget, initializeClaimedElement, initWidget, isAttached, onAttach, onBrowserEvent, onDetach, render, render, resolvePotentialElement, setWidget`

    - ### Methods inherited from class com.google.gwt.user.client.ui.Widget

      `addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, doAttachChildren, doDetachChildren, ensureHandlers, fireEvent, getHandlerCount, getHandlerManager, getLayoutData, getParent, isOrWasAttached, onLoad, onUnload, removeFromParent, replaceElement, setLayoutData, setParent, sinkEvents`

    - ### Methods inherited from class com.google.gwt.user.client.ui.UIObject

      `addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, removeStyleDependentName, removeStyleName, setElement, setElement, setHeight, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkBitlessEvent, toString, unsinkEvents`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface com.google.gwt.event.shared.HasHandlers

      `fireEvent`

- - ### Constructor Detail

    - #### TabBar

          public TabBar()

      Creates an empty tab bar.

  - ### Method Detail

    - #### addBeforeSelectionHandler

          public HandlerRegistration addBeforeSelectionHandler(BeforeSelectionHandler<java.lang.Integer> handler)

      Description copied from interface: `HasBeforeSelectionHandlers`
      Adds a `BeforeSelectionEvent` handler.
      Specified by:
        `addBeforeSelectionHandler` in interface `HasBeforeSelectionHandlers<java.lang.Integer>`
      Parameters:
        `handler` - the handler
      Returns:
        the registration for the event

    - #### addSelectionHandler

          public HandlerRegistration addSelectionHandler(SelectionHandler<java.lang.Integer> handler)

      Description copied from interface: `HasSelectionHandlers`
      Adds a `SelectionEvent` handler.
      Specified by:
        `addSelectionHandler` in interface `HasSelectionHandlers<java.lang.Integer>`
      Parameters:
        `handler` - the handler
      Returns:
        the registration for the event

    - #### addTab

          public void addTab(SafeHtml html)

      Adds a new tab with the specified text.
      Parameters:
        `html` - the new tab's html

    - #### addTab

          public void addTab(java.lang.String text)

      Adds a new tab with the specified text.
      Parameters:
        `text` - the new tab's text

    - #### addTab

          public void addTab(java.lang.String text,
                    boolean asHTML)

      Adds a new tab with the specified text.
      Parameters:
        `text` - the new tab's text
        `asHTML` - `true` to treat the specified text as html

    - #### addTab

          public void addTab(Widget widget)

      Adds a new tab with the specified widget.
      Parameters:
        `widget` - the new tab's widget

    - #### addTabListener

          @Deprecated
          public void addTabListener(TabListener listener)

      Deprecated. Use `addBeforeSelectionHandler(BeforeSelectionHandler)` and `addSelectionHandler(SelectionHandler)` instead
      Description copied from interface: `SourcesTabEvents`
      Adds a listener interface to receive click events.
      Specified by:
        `addTabListener` in interface `SourcesTabEvents`
      Parameters:
        `listener` - the listener interface to add

    - #### getSelectedTab

          public int getSelectedTab()

      Gets the tab that is currently selected.
      Returns:
        the selected tab

    - #### getTab

          public final TabBar.Tab getTab(int index)

      Gets the given tab. This method is final because the Tab interface will expand. Therefore it is highly likely that subclasses which implemented this method would end up breaking.
      Parameters:
        `index` - the tab's index
      Returns:
        the tab wrapper

    - #### getTabCount

          public int getTabCount()

      Gets the number of tabs present.
      Returns:
        the tab count

    - #### getTabHTML

          public java.lang.String getTabHTML(int index)

      Gets the specified tab's HTML.
      Parameters:
        `index` - the index of the tab whose HTML is to be retrieved
      Returns:
        the tab's HTML

    - #### insertTab

          public void insertTab(SafeHtml html,
                       int beforeIndex)

      Inserts a new tab at the specified index.
      Parameters:
        `html` - the new tab's html
        `beforeIndex` - the index before which this tab will be inserted

    - #### insertTab

          public void insertTab(java.lang.String text,
                       boolean asHTML,
                       int beforeIndex)

      Inserts a new tab at the specified index.
      Parameters:
        `text` - the new tab's text
        `asHTML` - `true` to treat the specified text as HTML
        `beforeIndex` - the index before which this tab will be inserted

    - #### insertTab

          public void insertTab(java.lang.String text,
                       int beforeIndex)

      Inserts a new tab at the specified index.
      Parameters:
        `text` - the new tab's text
        `beforeIndex` - the index before which this tab will be inserted

    - #### insertTab

          public void insertTab(Widget widget,
                       int beforeIndex)

      Inserts a new tab at the specified index.
      Parameters:
        `widget` - widget to be used in the new tab
        `beforeIndex` - the index before which this tab will be inserted

    - #### isTabEnabled

          public boolean isTabEnabled(int index)

      Check if a tab is enabled or disabled. If disabled, the user cannot select the tab.
      Parameters:
        `index` - the index of the tab
      Returns:
        true if the tab is enabled, false if disabled

    - #### onClick

          @Deprecated
          public void onClick(Widget sender)

      Deprecated. add a `BeforeSelectionHandler` instead. Alternatively, if you need to access to the individual tabs, add a click handler to each `TabBar.Tab` element instead.
      Description copied from interface: `ClickListener`
      Fired when the user clicks on a widget.
      Specified by:
        `onClick` in interface `ClickListener`
      Parameters:
        `sender` - the widget sending the event.

    - #### onKeyDown

          @Deprecated
          public void onKeyDown(Widget sender,
                                  char keyCode,
                                  int modifiers)

      Deprecated. add a key down handler to the individual `TabBar.Tab` objects instead.
      Description copied from interface: `KeyboardListener`
      Fired when the user depresses a physical key.
      Specified by:
        `onKeyDown` in interface `KeyboardListener`
      Parameters:
        `sender` - the widget that was focused when the event occurred.
        `keyCode` - the physical key that was depressed. Constants for this value are defined in this interface with the KEY prefix.
        `modifiers` - the modifier keys pressed at when the event occurred. This value is a combination of the bits defined by `KeyboardListener.MODIFIER_SHIFT`, `KeyboardListener.MODIFIER_CTRL`, and `KeyboardListener.MODIFIER_ALT`

    - #### onKeyPress

          @Deprecated
          public void onKeyPress(Widget sender,
                                   char keyCode,
                                   int modifiers)

      Deprecated. this method has been doing nothing for the entire last release, if what you wanted to do was to listen to key press events on tabs, add the key press handler to the individual tab wrappers instead.
      Description copied from interface: `KeyboardListener`
      Fired when a keyboard action generates a character. This occurs after onKeyDown and onKeyUp are fired for the physical key that was pressed.

      It should be noted that many browsers do not generate keypress events for non-printing keyCode values, such as `KeyboardListener.KEY_ENTER` or arrow keys. These keyCodes can be reliably captured either with `KeyboardListener.onKeyDown(Widget, char, int)` or `KeyboardListener.onKeyUp(Widget, char, int)`.

      Specified by:
        `onKeyPress` in interface `KeyboardListener`
      Parameters:
        `sender` - the widget that was focused when the event occurred.
        `keyCode` - the Unicode character that was generated by the keyboard action.
        `modifiers` - the modifier keys pressed at when the event occurred. This value is a combination of the bits defined by `KeyboardListener.MODIFIER_SHIFT`, `KeyboardListener.MODIFIER_CTRL`, and `KeyboardListener.MODIFIER_ALT`

    - #### onKeyUp

          @Deprecated
          public void onKeyUp(Widget sender,
                                char keyCode,
                                int modifiers)

      Deprecated. this method has been doing nothing for the entire last release, if what you wanted to do was to listen to key up events on tabs, add the key up handler to the individual tab wrappers instead.
      Description copied from interface: `KeyboardListener`
      Fired when the user releases a physical key.
      Specified by:
        `onKeyUp` in interface `KeyboardListener`
      Parameters:
        `sender` - the widget that was focused when the event occurred.
        `keyCode` - the physical key that was released. Constants for this value are defined in this interface with the KEY prefix.
        `modifiers` - the modifier keys pressed at when the event occurred. This value is a combination of the bits defined by `KeyboardListener.MODIFIER_SHIFT`, `KeyboardListener.MODIFIER_CTRL`, and `KeyboardListener.MODIFIER_ALT`

    - #### removeTab

          public void removeTab(int index)

      Removes the tab at the specified index.
      Parameters:
        `index` - the index of the tab to be removed

    - #### removeTabListener

          @Deprecated
          public void removeTabListener(TabListener listener)

      Deprecated. Instead use the `HandlerRegistration.removeHandler()` call on the object returned by an add*Handler method
      Description copied from interface: `SourcesTabEvents`
      Removes a previously added listener interface.
      Specified by:
        `removeTabListener` in interface `SourcesTabEvents`
      Parameters:
        `listener` - the listener interface to remove

    - #### selectTab

          public boolean selectTab(int index)

      Programmatically selects the specified tab and fires events. Use index -1 to specify that no tab should be selected.
      Parameters:
        `index` - the index of the tab to be selected
      Returns:
        `true` if successful, `false` if the change is denied by the `BeforeSelectionHandler`.

    - #### selectTab

          public boolean selectTab(int index,
                          boolean fireEvents)

      Programmatically selects the specified tab. Use index -1 to specify that no tab should be selected.
      Parameters:
        `index` - the index of the tab to be selected
        `fireEvents` - true to fire events, false not to
      Returns:
        `true` if successful, `false` if the change is denied by the `BeforeSelectionHandler`.

    - #### setTabEnabled

          public void setTabEnabled(int index,
                           boolean enabled)

      Enable or disable a tab. When disabled, users cannot select the tab.
      Parameters:
        `index` - the index of the tab to enable or disable
        `enabled` - true to enable, false to disable

    - #### setTabHTML

          public void setTabHTML(int index,
                        java.lang.String html)

      Sets a tab's contents via HTML. Use care when setting an object's HTML; it is an easy way to expose script-based security problems. Consider using `setTabText(int, String)` or `setTabHTML(int, SafeHtml)` whenever possible.
      Parameters:
        `index` - the index of the tab whose HTML is to be set
        `html` - the tab new HTML

    - #### setTabHTML

          public void setTabHTML(int index,
                        SafeHtml html)

      Sets a tab's contents via safe html.
      Parameters:
        `index` - the index of the tab whose HTML is to be set
        `html` - the tab new HTML

    - #### setTabText

          public void setTabText(int index,
                        java.lang.String text)

      Sets a tab's text contents.
      Parameters:
        `index` - the index of the tab whose text is to be set
        `text` - the object's new text

    - #### createTabTextWrapper

          protected SimplePanel createTabTextWrapper()

      Create a `SimplePanel` that will wrap the contents in a tab. Subclasses can use this method to wrap tabs in decorator panels.
      Returns:
        a `SimplePanel` to wrap the tab contents, or null to leave tabs unwrapped

    - #### insertTabWidget

          protected void insertTabWidget(Widget widget,
                             int beforeIndex)

      Inserts a new tab at the specified index.
      Parameters:
        `widget` - widget to be used in the new tab
        `beforeIndex` - the index before which this tab will be inserted

    - #### onEnsureDebugId

          protected void onEnsureDebugId(java.lang.String baseID)

      Affected Elements:
      - -tab# = The element containing the contents of the tab.
      - -tab-wrapper# = The cell containing the tab at the index.
      Overrides:
        `onEnsureDebugId` in class `UIObject`
      Parameters:
        `baseID` - the base ID used by the main element
      See Also:
        `UIObject.onEnsureDebugId(String)`