com.google.gwt.user.client.ui

## Class TreeItem

- java.lang.Object
- - com.google.gwt.user.client.ui.UIObject
  - - com.google.gwt.user.client.ui.TreeItem

- All Implemented Interfaces:
    HasSafeHtml, HasHTML, HasText, HasTreeItems, HasVisibility, IsTreeItem

      public class TreeItem
      extends UIObject
      implements IsTreeItem, HasTreeItems, HasHTML, HasSafeHtml

  An item that can be contained within a `Tree`. Each tree item is assigned a unique DOM id in order to support ARIA. See `Accessibility` for more information.

  ### Example

  >     public class TreeExample implements EntryPoint {

  >       @Override
  >       public void onModuleLoad() {
  >         // Create a tree with a few items in it.
  >         TreeItem root = new TreeItem();
  >         root.setText("root");
  >         root.addTextItem("item0");
  >         root.addTextItem("item1");
  >         root.addTextItem("item2");

  >         // Add a CheckBox to the tree
  >         TreeItem item = new TreeItem(new CheckBox("item3"));
  >         root.addItem(item);

  >         Tree t = new Tree();
  >         t.addItem(root);

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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `TreeItem.TreeItemImpl` Implementation class for `TreeItem`.
    `static class` | `TreeItem.TreeItemImplIE6` IE specific implementation class for `TreeItem`.

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

      `UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled`

    - ### Nested classes/interfaces inherited from interface com.google.gwt.user.client.ui.HasTreeItems

      `HasTreeItems.ForIsWidget`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) static int` | `IMAGE_PAD`

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

      `DEBUG_ID_PREFIX, MISSING_ELEMENT_ERROR, SETELEMENT_TWICE_ERROR`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TreeItem()` Creates an empty tree item.
    `TreeItem(boolean isRoot)` Creates an empty tree item.
    `TreeItem(SafeHtml html)` Constructs a tree item with the given HTML.
    `TreeItem(java.lang.String html)` Deprecated. use `TreeItem(SafeHtml)` instead
    `TreeItem(Widget widget)` Constructs a tree item with the given `Widget`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addItem(IsTreeItem isItem)` Adds another item as a child to this one.
    `TreeItem` | `addItem(SafeHtml itemHtml)` Adds a child tree item containing the specified html.
    `TreeItem` | `addItem(java.lang.String itemHtml)` Deprecated. use `addItem(SafeHtml)` instead
    `void` | `addItem(TreeItem item)` Adds another item as a child to this one.
    `TreeItem` | `addItem(Widget widget)` Adds a child tree item containing the specified widget.
    `TreeItem` | `addTextItem(java.lang.String itemText)` Adds a child tree item containing the specified text.
    `(package private) void` | `addTreeItems(java.util.List<TreeItem> accum)`
    `TreeItem` | `asTreeItem()` Returns the `TreeItem` aspect of the receiver.
    `TreeItem` | `getChild(int index)` Gets the child at the specified index.
    `int` | `getChildCount()` Gets the number of children contained in this item.
    `int` | `getChildIndex(TreeItem child)` Gets the index of the specified child item.
    `(package private) java.util.ArrayList<TreeItem>` | `getChildren()`
    `(package private) Element` | `getContentElem()`
    `protected Focusable` | `getFocusable()` Returns a suggested `Focusable` instance to use when this tree item is selected.
    `protected HasFocus` | `getFocusableWidget()` Deprecated. use `getFocusable()` instead
    `java.lang.String` | `getHTML()` Gets this object's contents as HTML.
    `(package private) Element` | `getImageElement()`
    `(package private) Element` | `getImageHolderElement()`
    `TreeItem` | `getParentItem()` Gets this item's parent.
    `boolean` | `getState()` Gets whether this item's children are displayed.
    `java.lang.String` | `getText()` Gets this object's text.
    `Tree` | `getTree()` Gets the tree that contains this item.
    `java.lang.Object` | `getUserObject()` Gets the user-defined object associated with this item.
    `Widget` | `getWidget()` Gets the `Widget` associated with this tree item.
    `(package private) void` | `initChildren()`
    `TreeItem` | `insertItem(int beforeIndex, SafeHtml itemHtml)` Inserts a child tree item at the specified index containing the specified html.
    `TreeItem` | `insertItem(int beforeIndex, java.lang.String itemHtml)` Deprecated. use `insertItem(int, SafeHtml)` instead
    `void` | `insertItem(int beforeIndex, TreeItem item)` Inserts an item as a child to this one.
    `TreeItem` | `insertItem(int beforeIndex, Widget widget)` Inserts a child tree item at the specified index containing the specified widget.
    `TreeItem` | `insertTextItem(int beforeIndex, java.lang.String itemText)` Inserts a child tree item at the specified index containing the specified text.
    `(package private) boolean` | `isFullNode()`
    `boolean` | `isSelected()` Determines whether this item is currently selected.
    `(package private) void` | `maybeRemoveItemFromParent(TreeItem item)` Remove a tree item from its parent if it has one.
    `protected void` | `onEnsureDebugId(java.lang.String baseID)` Affected Elements: -content = The text or `Widget` next to the image. -child# = The child at the specified index.
    `void` | `remove()` Removes this item from its tree.
    `void` | `removeItem(IsTreeItem isItem)` Removes one of this item's children.
    `void` | `removeItem(TreeItem item)` Removes one of this item's children.
    `void` | `removeItems()` Removes all of this item's children.
    `void` | `setHTML(SafeHtml html)` Sets this object's contents via known-safe HTML.
    `void` | `setHTML(java.lang.String html)` Sets this object's contents via HTML.
    `(package private) void` | `setParentItem(TreeItem parent)`
    `void` | `setSelected(boolean selected)` Selects or deselects this item.
    `void` | `setState(boolean open)` Sets whether this item's children are displayed.
    `void` | `setState(boolean open, boolean fireEvents)` Sets whether this item's children are displayed.
    `void` | `setText(java.lang.String text)` Sets this object's text.
    `(package private) void` | `setTree(Tree newTree)`
    `void` | `setUserObject(java.lang.Object userObj)` Sets the user-defined object associated with this item.
    `void` | `setWidget(Widget newWidget)` Sets the current widget.
    `(package private) void` | `updateState(boolean animate, boolean updateTreeSelection)`
    `(package private) void` | `updateStateRecursive()`

    - ### 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, replaceElement, resolvePotentialElement, setElement, setElement, setHeight, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkBitlessEvent, sinkEvents, toString, unsinkEvents`

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

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

- - ### Field Detail

    - #### IMAGE_PAD

          static final int IMAGE_PAD

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### TreeItem

          public TreeItem()

      Creates an empty tree item.

    - #### TreeItem

          @Deprecated
          public TreeItem(java.lang.String html)

      Deprecated. use `TreeItem(SafeHtml)` instead
      Constructs a tree item with the given HTML.
      Parameters:
        `html` - the item's HTML

    - #### TreeItem

          public TreeItem(SafeHtml html)

      Constructs a tree item with the given HTML.
      Parameters:
        `html` - the item's HTML

    - #### TreeItem

          public TreeItem(Widget widget)

      Constructs a tree item with the given `Widget`.
      Parameters:
        `widget` - the item's widget

    - #### TreeItem

          TreeItem(boolean isRoot)

      Creates an empty tree item.
      Parameters:
        `isRoot` - true if this item is the root of a tree

  - ### Method Detail

    - #### addItem

          @Deprecated
          public TreeItem addItem(java.lang.String itemHtml)

      Deprecated. use `addItem(SafeHtml)` instead
      Adds a child tree item containing the specified html.
      Parameters:
        `itemHtml` - the text to be added
      Returns:
        the item that was added

    - #### addItem

          public TreeItem addItem(SafeHtml itemHtml)

      Adds a child tree item containing the specified html.
      Specified by:
        `addItem` in interface `HasTreeItems`
      Parameters:
        `itemHtml` - the item's HTML
      Returns:
        the item that was added

    - #### addItem

          public void addItem(TreeItem item)

      Adds another item as a child to this one.
      Specified by:
        `addItem` in interface `HasTreeItems`
      Parameters:
        `item` - the item to be added

    - #### addItem

          public void addItem(IsTreeItem isItem)

      Adds another item as a child to this one.
      Specified by:
        `addItem` in interface `HasTreeItems`
      Parameters:
        `isItem` - the wrapper of item to be added

    - #### addItem

          public TreeItem addItem(Widget widget)

      Adds a child tree item containing the specified widget.
      Specified by:
        `addItem` in interface `HasTreeItems`
      Parameters:
        `widget` - the widget to be added
      Returns:
        the item that was added

    - #### addTextItem

          public TreeItem addTextItem(java.lang.String itemText)

      Adds a child tree item containing the specified text.
      Specified by:
        `addTextItem` in interface `HasTreeItems`
      Parameters:
        `itemText` - the text of the item to be added
      Returns:
        the item that was added

    - #### asTreeItem

          public TreeItem asTreeItem()

      Description copied from interface: `IsTreeItem`
      Returns the `TreeItem` aspect of the receiver.
      Specified by:
        `asTreeItem` in interface `IsTreeItem`

    - #### getChild

          public TreeItem getChild(int index)

      Gets the child at the specified index.
      Parameters:
        `index` - the index to be retrieved
      Returns:
        the item at that index

    - #### getChildCount

          public int getChildCount()

      Gets the number of children contained in this item.
      Returns:
        this item's child count.

    - #### getChildIndex

          public int getChildIndex(TreeItem child)

      Gets the index of the specified child item.
      Parameters:
        `child` - the child item to be found
      Returns:
        the child's index, or `-1` if none is found

    - #### getHTML

          public java.lang.String getHTML()

      Description copied from interface: `HasHTML`
      Gets this object's contents as HTML.
      Specified by:
        `getHTML` in interface `HasHTML`
      Returns:
        the object's HTML

    - #### getParentItem

          public TreeItem getParentItem()

      Gets this item's parent.
      Returns:
        the parent item

    - #### getState

          public boolean getState()

      Gets whether this item's children are displayed.
      Returns:
        `true` if the item is open

    - #### getText

          public java.lang.String getText()

      Description copied from interface: `HasText`
      Gets this object's text.
      Specified by:
        `getText` in interface `HasText`
      Returns:
        the object's text

    - #### getTree

          public final Tree getTree()

      Gets the tree that contains this item.
      Returns:
        the containing tree

    - #### getUserObject

          public java.lang.Object getUserObject()

      Gets the user-defined object associated with this item.
      Returns:
        the item's user-defined object

    - #### getWidget

          public Widget getWidget()

      Gets the `Widget` associated with this tree item.
      Returns:
        the widget

    - #### insertItem

          @Deprecated
          public TreeItem insertItem(int beforeIndex,
                                       java.lang.String itemHtml)
                              throws java.lang.IndexOutOfBoundsException

      Deprecated. use `insertItem(int, SafeHtml)` instead
      Inserts a child tree item at the specified index containing the specified html.
      Parameters:
        `beforeIndex` - the index where the item will be inserted
        `itemHtml` - the html that the item will contain
      Returns:
        the item that was added
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of range

    - #### insertItem

          public TreeItem insertItem(int beforeIndex,
                            SafeHtml itemHtml)
                              throws java.lang.IndexOutOfBoundsException

      Inserts a child tree item at the specified index containing the specified html.
      Parameters:
        `beforeIndex` - the index where the item will be inserted
        `itemHtml` - the item's HTML
      Returns:
        the item that was added
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of range

    - #### insertItem

          public void insertItem(int beforeIndex,
                        TreeItem item)
                          throws java.lang.IndexOutOfBoundsException

      Inserts an item as a child to this one.
      Parameters:
        `beforeIndex` - the index where the item will be inserted
        `item` - the item to be added
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of range

    - #### insertItem

          public TreeItem insertItem(int beforeIndex,
                            Widget widget)
                              throws java.lang.IndexOutOfBoundsException

      Inserts a child tree item at the specified index containing the specified widget.
      Parameters:
        `beforeIndex` - the index where the item will be inserted
        `widget` - the widget to be added
      Returns:
        the item that was added
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of range

    - #### insertTextItem

          public TreeItem insertTextItem(int beforeIndex,
                                java.lang.String itemText)

      Inserts a child tree item at the specified index containing the specified text.
      Parameters:
        `beforeIndex` - the index where the item will be inserted
        `itemText` - the item's text
      Returns:
        the item that was added
      Throws:
        `java.lang.IndexOutOfBoundsException` - if the index is out of range

    - #### isSelected

          public boolean isSelected()

      Determines whether this item is currently selected.
      Returns:
        `true` if it is selected

    - #### remove

          public void remove()

      Removes this item from its tree.

    - #### removeItem

          public void removeItem(TreeItem item)

      Removes one of this item's children.
      Specified by:
        `removeItem` in interface `HasTreeItems`
      Parameters:
        `item` - the item to be removed

    - #### removeItem

          public void removeItem(IsTreeItem isItem)

      Removes one of this item's children.
      Specified by:
        `removeItem` in interface `HasTreeItems`
      Parameters:
        `isItem` - the wrapper of item to be removed

    - #### removeItems

          public void removeItems()

      Removes all of this item's children.
      Specified by:
        `removeItems` in interface `HasTreeItems`

    - #### setHTML

          public void setHTML(java.lang.String html)

      Description copied from interface: `HasHTML`
      Sets this object'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 `HasText.setText(String)` whenever possible.
      Specified by:
        `setHTML` in interface `HasHTML`
      Parameters:
        `html` - the object's new HTML

    - #### setHTML

          public void setHTML(SafeHtml html)

      Description copied from interface: `HasSafeHtml`
      Sets this object's contents via known-safe HTML.

      The object will behave exactly the same as when a widget's `HasHTML.setHTML(String)` method is invoked; however the `SafeHtml` passed to this method observes the contract that it can be used in an HTML context without causing unsafe script execution. Thus, unlike `HasHTML.setHTML(String)`, using this method cannot result in Cross-Site Scripting security vulnerabilities.

      Specified by:
        `setHTML` in interface `HasSafeHtml`
      Parameters:
        `html` - the object's new HTML, represented as a `SafeHtml` object

    - #### setSelected

          public void setSelected(boolean selected)

      Selects or deselects this item.
      Parameters:
        `selected` - `true` to select the item, `false` to deselect it

    - #### setState

          public void setState(boolean open)

      Sets whether this item's children are displayed.
      Parameters:
        `open` - whether the item is open

    - #### setState

          public void setState(boolean open,
                      boolean fireEvents)

      Sets whether this item's children are displayed.
      Parameters:
        `open` - whether the item is open
        `fireEvents` - `true` to allow open/close events to be

    - #### setText

          public void setText(java.lang.String text)

      Description copied from interface: `HasText`
      Sets this object's text.
      Specified by:
        `setText` in interface `HasText`
      Parameters:
        `text` - the object's new text

    - #### setUserObject

          public void setUserObject(java.lang.Object userObj)

      Sets the user-defined object associated with this item.
      Parameters:
        `userObj` - the item's user-defined object

    - #### setWidget

          public void setWidget(Widget newWidget)

      Sets the current widget. Any existing child widget will be removed.
      Parameters:
        `newWidget` - Widget to set

    - #### getFocusable

          protected Focusable getFocusable()

      Returns a suggested `Focusable` instance to use when this tree item is selected. The tree maintains focus if this method returns null. By default, if the tree item contains a focusable widget, that widget is returned. Note, the `Tree` will ignore this value if the user clicked on an input element such as a button or text area when selecting this item.
      Returns:
        the focusable item

    - #### getFocusableWidget

          @Deprecated
          protected HasFocus getFocusableWidget()

      Deprecated. use `getFocusable()` instead
      Returns the widget, if any, that should be focused on if this TreeItem is selected.
      Returns:
        widget to be focused.

    - #### onEnsureDebugId

          protected void onEnsureDebugId(java.lang.String baseID)

      Affected Elements:
      - -content = The text or `Widget` next to the image.
      - -child# = The child at the specified index.
      Overrides:
        `onEnsureDebugId` in class `UIObject`
      Parameters:
        `baseID` - the base ID used by the main element
      See Also:
        `UIObject.onEnsureDebugId(String)`

    - #### addTreeItems

          void addTreeItems(java.util.List<TreeItem> accum)

    - #### getChildren

          java.util.ArrayList<TreeItem> getChildren()

    - #### getContentElem

          Element getContentElem()

    - #### getImageElement

          Element getImageElement()

    - #### getImageHolderElement

          Element getImageHolderElement()

    - #### initChildren

          void initChildren()

    - #### isFullNode

          boolean isFullNode()

    - #### maybeRemoveItemFromParent

          void maybeRemoveItemFromParent(TreeItem item)

      Remove a tree item from its parent if it has one.
      Parameters:
        `item` - the tree item to remove from its parent

    - #### setParentItem

          void setParentItem(TreeItem parent)

    - #### setTree

          void setTree(Tree newTree)

    - #### updateState

          void updateState(boolean animate,
                         boolean updateTreeSelection)

    - #### updateStateRecursive

          void updateStateRecursive()