Public Member Functions | Protected Member Functions

Wt::WTreeView Class Reference
[Model/view system]

A view class that displays a model as a tree or tree table. More...

#include <Wt/WTreeView>

Inherits Wt::WAbstractItemView.

List of all members.

Public Member Functions

 WTreeView (WContainerWidget *parent=0)
 Creates a new tree view.
 ~WTreeView ()
 Destructor.
void setRootIndex (const WModelIndex &rootIndex)
 Sets the root index.
const WModelIndexrootIndex () const
 Returns the root index.
void setColumnFormat (int column, const WString &format)
 Sets the column format string (deprecated).
WString columnFormat (int column) const
 Returns the column format string (deprecated).
void setExpanded (const WModelIndex &, bool expanded)
 Expands or collapses a node.
bool isExpanded (const WModelIndex &index) const
 Returns whether a node is expanded.
void collapse (const WModelIndex &index)
 Collapses a node.
void expand (const WModelIndex &index)
 Expands a node.
void expandToDepth (int depth)
 Expands all nodes to a depth.
virtual void setAlternatingRowColors (bool enable)
 Sets if alternating row colors are to be used. Configure whether rows get an alternating background color. These are implemented by using a background image on the root node, like:
virtual bool alternatingRowColors () const
 Returns whether alternating row colors are used.
void setRootIsDecorated (bool show)
 Sets whether toplevel items are decorated.
bool rootIsDecorated () const
 Returns whether toplevel items are decorated.
void setColumn1Fixed (bool enable)
 Configures whether horizontal scrolling includes the first column.
bool column1Fixed () const
 Returns whether horizontal scrolling includes the first column.
virtual void resize (const WLength &width, const WLength &height)
 Resizes the widget.
Signal< WModelIndex > & collapsed ()
 Signal emitted when a node is collapsed.
Signal< WModelIndex > & expanded ()
 Signal emitted when a node is expanded.
virtual void setModel (WAbstractItemModel *model)
 Sets the model.
virtual void setColumnWidth (int column, const WLength &width)
 Sets the column width.
virtual WLength columnWidth (int column) const
 Returns the column width.
virtual void setRowHeight (const WLength &rowHeight)
 Sets the row height.
virtual void setHeaderHeight (const WLength &height, bool multiLine=false)
 Sets the header height.
virtual void setColumnAlignment (int column, AlignmentFlag alignment)
 Sets the content alignment for a column.
virtual AlignmentFlag columnAlignment (int column) const
 Returns the content alignment for a column.
virtual void setHeaderAlignment (int column, AlignmentFlag alignment)
 Sets the header alignment for a column.
virtual AlignmentFlag headerAlignment (int column) const
 Returns the header alignment for a column.
virtual void setColumnBorder (const WColor &color)
 Sets the column border color.

Protected Member Functions

virtual void enableAjax ()
 Progresses to an Ajax-enabled widget.

Detailed Description

A view class that displays a model as a tree or tree table.

The view displays data from a WAbstractItemModel in a tree or tree table. It provides incremental rendering, allowing the display of data models of any size efficiently, without excessive use of client- or serverside resources. Data of all predefined roles is displayed (see also ItemDataRole), including text, icons, checkboxes, and tooltips .

By default, all but the first columns are given a width of 150px, and the first column takes the remaining size. Note that this may have as consequence that the first column's size is reduced to 0. Column widths of all columns, including the first column, can be set through the API method setColumnWidth(), and also by the user using handles provided in the header.

Optionally, the treeview may be configured so that the first column is always visible while scrolling through the other columns, which may be convenient if you wish to display a model with many columns. Use setColumn1Fixed() to enable this behaviour.

If the model supports sorting (WAbstractItemModel::sort()), such as the WStandardItemModel, then you can enable sorting buttons in the header, using setSortingEnabled().

You can allow selection on row or item level (using setSelectionBehavior()), and selection of single or multiple items (using setSelectionMode()), and listen for changes in the selection using the selectionChanged() signal.

You may enable drag & drop support for this view, whith awareness of the items in the model. When enabling dragging (see setDragEnabled()), the current selection may be dragged, but only when all items in the selection indicate support for dragging (controlled by the ItemIsDragEnabled flag), and if the model indicates a mime-type (controlled by WAbstractItemModel::mimeType()). Likewise, by enabling support for dropping (see setDropsEnabled()), the treeview may receive a drop event on a particular item, at least if the item indicates support for drops (controlled by the ItemIsDropEnabled flag).

You may also react to mouse click events on any item, by connecting to one of the clicked() or doubleClicked() signals.

Usage example:

 // WTreeView will display the data of a model
 Wt::WAbstractItemModel *model = ...

 // Create the WTreeView
 Wt::WTreeView *gitView = new Wt::WTreeView();
 gitView->resize(300, Wt::WLength::Auto);
 gitView->setSortingEnabled(false);
 gitView->setModel(model);
 gitView->setSelectionMode(SingleSelection);

CSS

The treeview is styled by the current CSS theme. The look can be overridden using the Wt-treeview CSS class and the following selectors.

Selectors that apply to the header:

.Wt-treeview .Wt-headerdiv         : header (background)
.Wt-treeview .Wt-header .Wt-label  : header label
.Wt-treeview .Wt-tv-rh             : column resize handle
.Wt-treeview .Wt-tv-sh-none        : column sort handle, no sorting
.Wt-treeview .Wt-tv-sh-up          : column sort handle, sort up
.Wt-treeview .Wt-tv-sh-down        : column sort handle, sort down

Selectors that apply to the tree decoration:

.Wt-treeview .Wt-trunk          : vertical line, trunk
.Wt-treeview .Wt-end            : vertical line, last item
.Wt-treeview .Wt-collapse       : collapse icon
.Wt-treeview .Wt-expand         : expand icon
.Wt-treeview .Wt-noexpand       : leaf icon

Selectors that apply to the table contents:

.Wt-treeview .Wt-spacer         : spacer for non-loaded content
.Wt-treeview .Wt-selected       : selected item
.Wt-treeview .Wt-drop-site      : possible drop site

Selectors that apply to the table borders (which must be 1 pixel wide)

.Wt-treeview .Wt-tv-row .Wt-tv-c      : border-right property of cells
.Wt-treeview .Wt-header .Wt-tv-row,
  .Wt-treeview .Wt-tv-node .Wt-tv-row : border-left property of cells

A snapshot of the WTreeView:

WTreeView-default-1.png

WTreeView example (default)

WTreeView-polished-1.png

WTreeView example (polished)


Member Function Documentation

virtual bool Wt::WTreeView::alternatingRowColors (  )  const [inline, virtual]

Returns whether alternating row colors are used.

See also:
setAlternatingRowColors()

Implements Wt::WAbstractItemView.

void Wt::WTreeView::collapse ( const WModelIndex index  ) 

Collapses a node.

See also:
setExpanded(), expand()
Signal<WModelIndex>& Wt::WTreeView::collapsed (  )  [inline]

Signal emitted when a node is collapsed.

See also:
setExpanded(), expanded()
bool Wt::WTreeView::column1Fixed (  )  const [inline]

Returns whether horizontal scrolling includes the first column.

See also:
setColumn1Fixed()
virtual AlignmentFlag Wt::WTreeView::columnAlignment ( int  column  )  const [virtual]

Returns the content alignment for a column.

See also:
setColumnAlignment()

Implements Wt::WAbstractItemView.

WString Wt::WTreeView::columnFormat ( int  column  )  const

Returns the column format string (deprecated).

See also:
setColumnFormat()
Deprecated:
use itemDelegateForColumn() to customize the formatting. This method will try to cast the itemDelegateForColumn() to a WItemDelegate and return the format.
virtual WLength Wt::WTreeView::columnWidth ( int  column  )  const [virtual]

Returns the column width.

See also:
setColumnWidth()

Implements Wt::WAbstractItemView.

virtual void Wt::WTreeView::enableAjax (  )  [protected, virtual]

Progresses to an Ajax-enabled widget.

This method is called when the progressive bootstrap method is used, and support for AJAX has been detected. The default behavior will upgrade the widget's event handling to use AJAX instead of full page reloads, and propagate the call to its children.

You may want to reimplement this method if you want to make changes to widget when AJAX is enabled. You should always call the base implementation.

See also:
WApplication::enableAjax()

Reimplemented from Wt::WCompositeWidget.

void Wt::WTreeView::expand ( const WModelIndex index  ) 

Expands a node.

See also:
setExpanded(), collapse()
Signal<WModelIndex>& Wt::WTreeView::expanded (  )  [inline]

Signal emitted when a node is expanded.

See also:
setExpanded(), collapsed()
void Wt::WTreeView::expandToDepth ( int  depth  ) 

Expands all nodes to a depth.

Expands all nodes to the given depth. A depth of 1 corresponds to the top level nodes.

See also:
expand()
virtual AlignmentFlag Wt::WTreeView::headerAlignment ( int  column  )  const [virtual]

Returns the header alignment for a column.

See also:
setHeaderAlignment()

Implements Wt::WAbstractItemView.

bool Wt::WTreeView::isExpanded ( const WModelIndex index  )  const

Returns whether a node is expanded.

See also:
setExpanded()
virtual void Wt::WTreeView::resize ( const WLength width,
const WLength height 
) [virtual]

Resizes the widget.

Specify a new size for this widget, by specifying width and height. By default a widget has automatic width and height, see WLength::isAuto().

This applies to CSS-based layout, and only block widgets can be given a size reliably.

When inserted in a layout manager, the widget may be informed about its current size using setLayoutSizeAware(). If you have defined a "wtResize()" JavaScript method for the widget, then this method will also be called. operation.

See also:
width(), height()

Reimplemented from Wt::WCompositeWidget.

const WModelIndex& Wt::WTreeView::rootIndex (  )  const [inline]

Returns the root index.

See also:
setRootIndex()
bool Wt::WTreeView::rootIsDecorated (  )  const [inline]

Returns whether toplevel items are decorated.

See also:
setRootIsDecorated()
virtual void Wt::WTreeView::setAlternatingRowColors ( bool  enable  )  [virtual]

Sets if alternating row colors are to be used. Configure whether rows get an alternating background color. These are implemented by using a background image on the root node, like:

stripe-30px.gif

Sample image use for alternating row colors

The image that is used is resourcesURL"/stripes/stripe-<i>n</i>px.gif", where n is the row height. In the resource folder are images pregenerated for one color and row sizes from 10 to 30px.

The default value is false.

See also:
setImagePack()

Implements Wt::WAbstractItemView.

void Wt::WTreeView::setColumn1Fixed ( bool  enable  ) 

Configures whether horizontal scrolling includes the first column.

To display a model with many columns, this option allows you to keep the first column fixed while scrolling through the other columns of the model.

The default value is false.

Note:
Currently, you must set this option before any other manipulation of a newly created treeview, and only enable = true is supported.
virtual void Wt::WTreeView::setColumnAlignment ( int  column,
AlignmentFlag  alignment 
) [virtual]

Sets the content alignment for a column.

The default value is AlignLeft.

Note:
For column 0, AlignCenter is currently not supported.
See also:
setHeaderAlignment()

Implements Wt::WAbstractItemView.

virtual void Wt::WTreeView::setColumnBorder ( const WColor color  )  [virtual]

Sets the column border color.

The default border color is white.

Implements Wt::WAbstractItemView.

void Wt::WTreeView::setColumnFormat ( int  column,
const WString format 
)

Sets the column format string (deprecated).

The DisplayRole data for that column is converted to a string using asString(), with the given format.

The default value is "".

Deprecated:
use itemDelegateForColumn() to customize the formatting. This method will create a new WItemDelegate for the column, and configure its format.
virtual void Wt::WTreeView::setColumnWidth ( int  column,
const WLength width 
) [virtual]

Sets the column width.

For a model with columnCount() == N, the initial width of columns 1..N is set to 150 pixels, and column 0 will take all remaining space.

Note:
The actual space occupied by each column is the column width augmented by 7 pixels for internal padding and a border.
See also:
setRowHeight()

Implements Wt::WAbstractItemView.

void Wt::WTreeView::setExpanded ( const WModelIndex ,
bool  expanded 
)

Expands or collapses a node.

See also:
expand(), collapse()
virtual void Wt::WTreeView::setHeaderAlignment ( int  column,
AlignmentFlag  alignment 
) [virtual]

Sets the header alignment for a column.

The default value is AlignLeft.

See also:
setColumnAlignment()

Implements Wt::WAbstractItemView.

virtual void Wt::WTreeView::setHeaderHeight ( const WLength height,
bool  multiLine = false 
) [virtual]

Sets the header height.

Use this method to change the header height. You may also enable the use of multi-line headers. By default, the header text is a single line, that is centered vertically.

The default value is 20 pixels.

Implements Wt::WAbstractItemView.

virtual void Wt::WTreeView::setModel ( WAbstractItemModel model  )  [virtual]

Sets the model.

The view will render the data in the given model. Changes to the model are reflected in the view.

The initial model is 0.

Ownership of the model is not transferred (and thus the previously set model is not deleted).

See also:
setRootIndex()

Reimplemented from Wt::WAbstractItemView.

void Wt::WTreeView::setRootIndex ( const WModelIndex rootIndex  ) 

Sets the root index.

The root index is the model index that is considered the root node. This node itself is not rendered, but all its children are the top level nodes.

The default value is WModelIndex(), corresponding to the invisible root.

See also:
setModel()
void Wt::WTreeView::setRootIsDecorated ( bool  show  ) 

Sets whether toplevel items are decorated.

By default, top level nodes have expand/collapse and other lines to display their linkage and offspring, like any node.

By setting show to false, you can hide these decorations for root nodes, and in this way mimic a plain list.

See also:
Ext::TableView
virtual void Wt::WTreeView::setRowHeight ( const WLength rowHeight  )  [virtual]

Sets the row height.

The view assumes that all rows are of the same height. Use this method to set the height.

The default value is 20 pixels.

Note:
The height must be specified in WLength::Pixel units.
See also:
setColumnWidth()

Implements Wt::WAbstractItemView.


Generated on Mon Nov 29 2010 08:03:19 for Wt by doxygen 1.7.1