com.sencha.gxt.widget.core.client.treegrid
Class TreeGrid<M>

java.lang.Object
  com.google.gwt.user.client.ui.UIObject
      com.google.gwt.user.client.ui.Widget
          com.sencha.gxt.widget.core.client.Component
              com.sencha.gxt.widget.core.client.grid.Grid<M>
                  com.sencha.gxt.widget.core.client.treegrid.TreeGrid<M>

Type Parameters:

M - the model type

All Implemented Interfaces:

HasAttachHandlers, HasResizeHandlers, HasHandlers, EventListener, HasEnabled, HasVisibility, IsWidget, BeforeCollapseItemEvent.HasBeforeCollapseItemHandlers<M>, BeforeExpandItemEvent.HasBeforeExpandItemHandlers<M>, BeforeHideEvent.HasBeforeHideHandlers, BeforeShowContextMenuEvent.HasBeforeShowContextMenuHandler, BeforeShowEvent.HasBeforeShowHandlers, BlurEvent.HasBlurHandlers, BodyScrollEvent.HasBodyScrollHandlers, CellClickEvent.HasCellClickHandlers, CellDoubleClickEvent.HasCellDoubleClickHandlers, CellMouseDownEvent.HasCellMouseDownHandlers, CollapseItemEvent.HasCollapseItemHandlers<M>, DisableEvent.HasDisableHandlers, EnableEvent.HasEnableHandlers, ExpandItemEvent.HasExpandItemHandlers<M>, FocusEvent.HasFocusHandlers, HeaderClickEvent.HasHeaderClickHandlers, HeaderContextMenuEvent.HasHeaderContextMenuHandlers, HeaderDoubleClickEvent.HasHeaderDoubleClickHandlers, HeaderMouseDownEvent.HasHeaderMouseDownHandlers, HideEvent.HasHideHandlers, MoveEvent.HasMoveHandlers, ReconfigureEvent.HasReconfigureHandlers, RefreshEvent.HasRefreshHandlers, RowClickEvent.HasRowClickHandlers, RowDoubleClickEvent.HasRowDoubleClickHandlers, RowMouseDownEvent.HasRowMouseDownHandlers, ShowContextMenuEvent.HasShowContextMenuHandler, ShowEvent.HasShowHandlers, SortChangeEvent.HasSortChangeHandlers, ViewReadyEvent.HasViewReadyHandlers, HasFocusSupport, HasItemId

public class TreeGrid<M>
extends Grid<M>
implements BeforeCollapseItemEvent.HasBeforeCollapseItemHandlers<M>, CollapseItemEvent.HasCollapseItemHandlers<M>, BeforeExpandItemEvent.HasBeforeExpandItemHandlers<M>, ExpandItemEvent.HasExpandItemHandlers<M>

A TreeGrid provides support for displaying and editing hierarchical data where each item may contain multiple properties. The tree grid gets its data from a TreeStore and its column definitions from a ColumnModel. Each model in the store is rendered as an item in the tree. The fields in the model provide the data for each column associated with the item. Any updates to the store are automatically pushed to the tree grid. This includes inserting, removing, sorting and filter.

In GXT version 3, ModelKeyProviders and ValueProviders provide the interface between your data model and the list store and ColumnConfig classes. This enables a tree grid to work with data of any object type.

You can provide your own implementation of these interfaces, or you can use a Sencha supplied generator to create them for you automatically. A generator runs at compile time to create a Java class that is compiled to JavaScript. The Sencha supplied generator can create classes for interfaces that extend the PropertyAccess interface. The generator transparently creates the class at compile time and the GWT.create(Class) method returns an instance of that class at run time. The generated class is managed by GWT and GXT and you generally do not need to worry about what the class is called, where it is located, or other similar details.

Each tree grid has a GridView. The grid view provides many options for customizing the grid's appearance (e.g. striping, mouse-over tracking, empty text). To set these options, get the current grid view using Grid.getView() and then set the desired option on the grid view.

To customize the appearance of a column in a tree grid, provide a cell implementation using ColumnConfig.setCell(Cell).

Tree grids support several ways to manage column widths:

1. The most basic approach is to simply give pixel widths to each column. Columns widths will match the specified values.
2. A column can be identified as an auto-expand column. As the width of the tree grid changes, or columns are resized, the specified column's width is adjusted so that the column fills the available width with no horizontal scrolling. See @link GridView.setAutoExpandColumn(ColumnConfig).
3. The tree grid can resize columns based on relative weights, determined by the pixel width assigned to each column. As the width of the tree grid or columns change, the weight is used to allocate the available space. Use GridView.setAutoFill(boolean) or GridView.setForceFit(boolean) to enable this feature:
• With auto fill, the calculations are run when the tree grid is created (or reconfigured). After the tree grid is rendered, the column widths will not be adjusted when the available width changes.
• With force fit the width calculations are run every time there are changes to the available width or column sizes.
4. To prevent a column from participating in auto fill or force fit, use ColumnConfig.setFixed(boolean).

The following code snippet illustrates the creation of a simple tree grid with local data for test purposes. For more practical examples that show how to load data from remote sources, see the Async TreeGrid example in the online Explorer demo.

// Generate the key provider and value provider for the Data class
    DataProperties dp = GWT.create(DataProperties.class);

    // Create the configurations for each column in the tree grid
    List<ColumnConfig<Data, ?>> ccs = new LinkedList<ColumnConfig<Data, ?>>();
    ccs.add(new ColumnConfig<Data, String>(dp.name(), 200, "Name"));
    ccs.add(new ColumnConfig<Data, String>(dp.value(), 200, "Value"));
    ColumnModel<Data> cm = new ColumnModel<Test.Data>(ccs);

    // Create the store that the contains the data to display in the tree grid
    TreeStore<Data> s = new TreeStore<Test.Data>(dp.key());

    Data r1 = new Data("Parent 1", "value1");
    s.add(r1);
    s.add(r1, new Data("Child 1.1", "value2"));
    s.add(r1, new Data("Child 1.2", "value3"));

    Data r2 = new Data("Parent 2", "value4");
    s.add(r2);
    s.add(r2, new Data("Child 2.1", "value5"));
    s.add(r2, new Data("Child 2.2", "value6"));

    // Create the tree grid using the store, column model and column config for the tree column
    TreeGrid<Data> tg = new TreeGrid<Data>(s, cm, ccs.get(0));

    // Add the tree to a container
    RootPanel.get().add(tg);
 

To use the Sencha supplied generator to create model key providers and value providers, extend the PropertyAccess interface, parameterized with the type of data you want to access (as shown below) and invoke the GWT.create method on its class member (as shown in the code snippet above). This creates an instance of the class that can be used to initialize the tree and tree store. In the following code snippet we define a new interface called DataProperties that extends the PropertyAccess interface and is parameterized with Data, a Plain Old Java Object (POJO).

  public interface DataProperties extends PropertyAccess {
    @Path("name")
    ModelKeyProvider key();
    ValueProvider<Data, String> name();
    ValueProvider<Data, String> value();
  }

  public class Data {
    private String name;
    private String value;

    public Data(String name, String value) {
      super();
      this.name = name;
      this.value = value;
    }
    public String getName() {
      return name;
    }
    public String getValue() {
      return value;
    }
    public void setName(String name) {
      this.name = name;
    }
    public void setValue(String value) {
      this.value = value;
    }
  }
 

To enable drag and drop for a tree grid, add the following:

    new TreeGridDragSource(tg);
    TreeGridDropTarget dt = new TreeGridDropTarget(tg);
    dt.setFeedback(Feedback.BOTH);
 

To add reordering support to the drag and drop, include:

    dt.setAllowSelfAsSource(true);
 

Nested Class Summary

static class

TreeGrid.TreeGridNode<M>

Nested classes/interfaces inherited from class com.sencha.gxt.widget.core.client.grid.Grid

Grid.Callback, Grid.GridCell

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.UIObject

DEBUG_ID_PREFIX

Constructor Summary

TreeGrid(TreeStore<M> store, ColumnModel<M> cm, ColumnConfig<M,?> treeColumn)
Creates a new tree grid.

TreeGrid(TreeStore<M> store, ColumnModel<M> cm, ColumnConfig<M,?> treeColumn, GridView.GridAppearance appearance)
Creates a new tree grid.

TreeGrid(TreeStore<M> store, ColumnModel<M> cm, ColumnConfig<M,?> treeColumn, GridView.GridAppearance appearance, Tree.TreeAppearance treeAppearance)
Creates a new tree grid.

Method Summary

HandlerRegistration	addBeforeCollapseHandler(BeforeCollapseItemEvent.BeforeCollapseItemHandler<M> handler) Adds a BeforeCollapseItemEvent.BeforeCollapseItemHandler handler for BeforeCollapseItemEvent events.
HandlerRegistration	addBeforeExpandHandler(BeforeExpandItemEvent.BeforeExpandItemHandler<M> handler) Adds a BeforeExpandItemEvent.BeforeExpandItemHandler handler for BeforeExpandItemEvent events.
HandlerRegistration	addCollapseHandler(CollapseItemEvent.CollapseItemHandler<M> handler) Adds a CollapseItemEvent.CollapseItemHandler handler for CollapseItemEvent events.
HandlerRegistration	addExpandHandler(ExpandItemEvent.ExpandItemHandler<M> handler) Adds a ExpandItemEvent.ExpandItemHandler handler for ExpandItemEvent events.
void	collapseAll() Collapses all nodes.
void	expandAll() Expands all nodes.
Tree.TreeNode<M>	findNode(Element target) Returns the tree node for the given target.
GridView.GridAppearance	getAppearance() Returns the grid appearance.
IconProvider<M>	getIconProvider() Returns the model icon provider.
TreeStyle	getStyle() Returns the tree style.
Tree.TreeAppearance	getTreeAppearance() Returns the tree appearance.
ColumnConfig<M,?>	getTreeColumn() Returns the column that represents the tree nodes.
TreeLoader<M>	getTreeLoader() Returns the tree loader.
TreeStore<M>	getTreeStore() Returns the tree's tree store.
TreeGridView<M>	getTreeView() Returns the tree's view.
boolean	isAutoExpand() Returns true if auto expand is enabled.
boolean	isAutoLoad() Returns true if auto load is enabled.
boolean	isCaching() Returns true when a loader is queried for it's children each time a node is expanded.
boolean	isExpanded(M model) Returns true if the model is expanded.
boolean	isExpandOnFilter() Returns the if expand all and collapse all is enabled on filter changes.
boolean	isLeaf(M model) Returns true if the model is a leaf node.
void	reconfigure(ListStore<M> store, ColumnModel<M> cm) Reconfigures the grid to use a different Store and Column Model.
void	reconfigure(TreeStore<M> store, ColumnModel<M> cm, ColumnConfig<M,?> treeColumn)
void	refresh(M model) Refreshes the data for the given model.
void	setAutoExpand(boolean autoExpand) If set to true, all non leaf nodes will be expanded automatically (defaults to false).
void	setAutoLoad(boolean autoLoad) Sets whether all children should automatically be loaded recursively (defaults to false).
void	setCaching(boolean caching) Sets whether the children should be cached after first being retrieved from the store (defaults to true).
void	setExpanded(M model, boolean expand) Sets the item's expand state.
void	setExpanded(M model, boolean expand, boolean deep) Sets the item's expand state.
void	setExpandOnFilter(boolean expandOnFilter) Sets whether the tree should expand all and collapse all when filters are applied (defaults to true).
void	setIconProvider(IconProvider<M> iconProvider) Sets the tree's model icon provider which provides the icon style for each model.
void	setLeaf(M model, boolean leaf) Sets the item's leaf state.
void	setTreeLoader(TreeLoader<M> treeLoader) Sets the tree loader.
void	setView(GridView<M> view) Sets the view's grid (pre-render).
void	toggle(M model) Toggles the model's expand state.

Methods inherited from class com.sencha.gxt.widget.core.client.grid.Grid

addBodyScrollHandler, addCellClickHandler, addCellDoubleClickHandler, addCellMouseDownHandler, addHeaderClickHandler, addHeaderContextMenuHandler, addHeaderDoubleClickHandler, addHeaderMouseDownHandler, addReconfigureHandler, addRefreshHandler, addRowClickHandler, addRowDoubleClickHandler, addRowMouseDownHandler, addSortChangeHandler, addViewReadyHandler, focus, getColumnModel, getLazyRowRender, getLoader, getMinColumnWidth, getSelectionModel, getStore, getView, isColumnReordering, isColumnResize, isHideHeaders, isLoadMask, isViewReady, onBrowserEvent, setAllowTextSelection, setColumnReordering, setColumnResize, setHideHeaders, setLazyRowRender, setLoader, setLoadMask, setMinColumnWidth, setSelectionModel, walkCells

Methods inherited from class com.sencha.gxt.widget.core.client.Component

addBeforeHideHandler, addBeforeShowContextMenuHandler, addBeforeShowHandler, addBlurHandler, addDisableHandler, addEnableHandler, addFocusHandler, addHideHandler, addMoveHandler, addResizeHandler, addShowContextMenuHandler, addShowHandler, addStyleOnOver, clearSizeCache, disable, disableEvents, enable, enableEvents, fireEvent, getData, getElement, getFocusSupport, getHideMode, getId, getItemId, getOffsetHeight, getOffsetWidth, getShadow, getStateId, getToolTip, hide, hideToolTip, isAllowTextSelection, isAutoHeight, isAutoWidth, isDeferHeight, isEnabled, isRendered, isStateful, isVisible, isVisible, mask, mask, removeToolTip, setBorders, setBounds, setBounds, setContextMenu, setData, setDeferHeight, setEnabled, setHeight, setHeight, setHideMode, setId, setItemId, setPagePosition, setPixelSize, setPosition, setShadow, setSize, setStateful, setStateId, setTabIndex, setToolTip, setToolTipConfig, setVisible, setWidth, setWidth, show, sync, syncSize, unmask

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

addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, getLayoutData, getParent, isAttached, removeFromParent, setLayoutData, sinkEvents

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

addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getOffsetHeight, getOffsetWidth, getStyleName, getStylePrimaryName, getTitle, isVisible, removeStyleDependentName, removeStyleName, setStyleDependentName, setStyleName, setStyleName, setStylePrimaryName, setTitle, setVisible, sinkBitlessEvent, toString, unsinkEvents

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

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

fireEvent

Constructor Detail

TreeGrid

public TreeGrid(TreeStore<M> store,
                ColumnModel<M> cm,
                ColumnConfig<M,?> treeColumn)

Creates a new tree grid.

Parameters:

store - the tree store

cm - the column model

treeColumn - the tree column

TreeGrid

public TreeGrid(TreeStore<M> store,
                ColumnModel<M> cm,
                ColumnConfig<M,?> treeColumn,
                GridView.GridAppearance appearance)

Creates a new tree grid.

Parameters:

store - the tree store

cm - the column model

treeColumn - the tree column

appearance - the grid appearance

TreeGrid

public TreeGrid(TreeStore<M> store,
                ColumnModel<M> cm,
                ColumnConfig<M,?> treeColumn,
                GridView.GridAppearance appearance,
                Tree.TreeAppearance treeAppearance)

Creates a new tree grid.

Parameters:

store - the tree store

cm - the column model

treeColumn - the tree column

appearance - the grid appearance

treeAppearance - the tree appearance

Method Detail

addBeforeCollapseHandler

public HandlerRegistration addBeforeCollapseHandler(BeforeCollapseItemEvent.BeforeCollapseItemHandler<M> handler)

Description copied from interface: BeforeCollapseItemEvent.HasBeforeCollapseItemHandlers

Adds a BeforeCollapseItemEvent.BeforeCollapseItemHandler handler for BeforeCollapseItemEvent events.

Specified by:

addBeforeCollapseHandler in interface BeforeCollapseItemEvent.HasBeforeCollapseItemHandlers<M>

Parameters:

handler - the handler

Returns:

the registration for the event

addBeforeExpandHandler

public HandlerRegistration addBeforeExpandHandler(BeforeExpandItemEvent.BeforeExpandItemHandler<M> handler)

Description copied from interface: BeforeExpandItemEvent.HasBeforeExpandItemHandlers

Adds a BeforeExpandItemEvent.BeforeExpandItemHandler handler for BeforeExpandItemEvent events.

Specified by:

addBeforeExpandHandler in interface BeforeExpandItemEvent.HasBeforeExpandItemHandlers<M>

Parameters:

handler - the handler

Returns:

the registration for the event

addCollapseHandler

public HandlerRegistration addCollapseHandler(CollapseItemEvent.CollapseItemHandler<M> handler)

Description copied from interface: CollapseItemEvent.HasCollapseItemHandlers

Adds a CollapseItemEvent.CollapseItemHandler handler for CollapseItemEvent events.

Specified by:

addCollapseHandler in interface CollapseItemEvent.HasCollapseItemHandlers<M>

Parameters:

handler - the handler

Returns:

the registration for the event

addExpandHandler

public HandlerRegistration addExpandHandler(ExpandItemEvent.ExpandItemHandler<M> handler)

Description copied from interface: ExpandItemEvent.HasExpandItemHandlers

Adds a ExpandItemEvent.ExpandItemHandler handler for ExpandItemEvent events.

Specified by:

addExpandHandler in interface ExpandItemEvent.HasExpandItemHandlers<M>

Parameters:

handler - the handler

Returns:

the registration for the event

collapseAll

public void collapseAll()

Collapses all nodes.

expandAll

public void expandAll()

Expands all nodes.

findNode

public Tree.TreeNode<M> findNode(Element target)

Returns the tree node for the given target.

Parameters:

target - the target element

Returns:

the tree node or null if no match

getAppearance

public GridView.GridAppearance getAppearance()

Returns the grid appearance.

Returns:

the grid appearance

getIconProvider

public IconProvider<M> getIconProvider()

Returns the model icon provider.

Returns:

the icon provider

getStyle

public TreeStyle getStyle()

Returns the tree style.

Returns:

the tree style

getTreeAppearance

public Tree.TreeAppearance getTreeAppearance()

Returns the tree appearance.

Returns:

the tree appearance

getTreeColumn

public ColumnConfig<M,?> getTreeColumn()

Returns the column that represents the tree nodes.

Returns:

the tree column

getTreeLoader

public TreeLoader<M> getTreeLoader()

Returns the tree loader.

Returns:

the tree loader or null if not specified

getTreeStore

public TreeStore<M> getTreeStore()

Returns the tree's tree store.

Returns:

the tree store

getTreeView

public TreeGridView<M> getTreeView()

Returns the tree's view.

Returns:

the view

isAutoExpand

public boolean isAutoExpand()

Returns true if auto expand is enabled.

Returns:

the auto expand state

isAutoLoad

public boolean isAutoLoad()

Returns true if auto load is enabled.

Returns:

the auto load state

isCaching

public boolean isCaching()

Returns true when a loader is queried for it's children each time a node is expanded. Only applies when using a loader with the tree store.

Returns:

true if caching

isExpanded

public boolean isExpanded(M model)

Returns true if the model is expanded.

Parameters:

model - the model

Returns:

true if expanded

isExpandOnFilter

public boolean isExpandOnFilter()

Returns the if expand all and collapse all is enabled on filter changes.

Returns:

the expand all collapse all state

isLeaf

public boolean isLeaf(M model)

Returns true if the model is a leaf node. The leaf state allows a tree item to specify if it has children before the children have been realized.

Parameters:

model - the model

Returns:

the leaf state

reconfigure

public void reconfigure(ListStore<M> store,
                        ColumnModel<M> cm)

Description copied from class: Grid

Reconfigures the grid to use a different Store and Column Model. The View will be bound to the new objects and refreshed.

Overrides:

reconfigure in class Grid<M>

Parameters:

store - the new store

cm - the new column model

reconfigure

public void reconfigure(TreeStore<M> store,
                        ColumnModel<M> cm,
                        ColumnConfig<M,?> treeColumn)

refresh

public void refresh(M model)

Refreshes the data for the given model.

Parameters:

model - the model to be refreshed

setAutoExpand

public void setAutoExpand(boolean autoExpand)

If set to true, all non leaf nodes will be expanded automatically (defaults to false).

Parameters:

autoExpand - the auto expand state to set.

setAutoLoad

public void setAutoLoad(boolean autoLoad)

Sets whether all children should automatically be loaded recursively (defaults to false). Useful when the tree must be fully populated when initially rendered.

Parameters:

autoLoad - true to auto load

setCaching

public void setCaching(boolean caching)

Sets whether the children should be cached after first being retrieved from the store (defaults to true). When false, a load request will be made each time a node is expanded.

Parameters:

caching - the caching state

setExpanded

public void setExpanded(M model,
                        boolean expand)

Sets the item's expand state.

Parameters:

model - the model

expand - true to expand

setExpanded

public void setExpanded(M model,
                        boolean expand,
                        boolean deep)

Sets the item's expand state.

Parameters:

model - the model

expand - true to expand

deep - true to expand all children recursively

setExpandOnFilter

public void setExpandOnFilter(boolean expandOnFilter)

Sets whether the tree should expand all and collapse all when filters are applied (defaults to true).

Parameters:

expandOnFilter - true to expand and collapse on filter changes

setIconProvider

public void setIconProvider(IconProvider<M> iconProvider)

Sets the tree's model icon provider which provides the icon style for each model.

Parameters:

iconProvider - the icon provider

setLeaf

public void setLeaf(M model,
                    boolean leaf)

Sets the item's leaf state. The leaf state allows control of the expand icon before the children have been realized.

Parameters:

model - the model

leaf - the leaf state

setTreeLoader

public void setTreeLoader(TreeLoader<M> treeLoader)

Sets the tree loader.

Parameters:

treeLoader - the tree loader

setView

public void setView(GridView<M> view)

Description copied from class: Grid

Sets the view's grid (pre-render).

Overrides:

setView in class Grid<M>

Parameters:

view - the view

toggle

public void toggle(M model)

Toggles the model's expand state.

Parameters:

model - the model