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

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

#include <Wt/WTreeView>

Inheritance diagram for Wt::WTreeView:

Inheritance graph
[legend]

List of all members.

Public Member Functions

 WTreeView (WContainerWidget *parent=0)
 Create a new tree view.
 ~WTreeView ()
 Destructor.
void setModel (WAbstractItemModel *model)
 Sets the model.
WAbstractItemModelmodel () const
 Returns the model.
void setRootIndex (const WModelIndex &rootIndex)
 Sets the root index.
const WModelIndexrootIndex () const
 Returns the root index.
void setHeaderHeight (const WLength &height, bool multiLine=false)
 Sets the header height.
const WLengthheaderHeight () const
 Returns the header height.
void setRowHeight (const WLength &rowHeight)
 Sets the row height.
const WLengthrowHeight () const
 Returns the row height.
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 setColumnWidth (int column, const WLength &width)
 Sets the column width.
WLength columnWidth (int column) const
 Returns the column width.
void setColumnAlignment (int column, AlignmentFlag alignment)
 Sets the content alignment for a column.
void setHeaderAlignment (int column, AlignmentFlag alignment)
 Sets the header alignment for a column.
AlignmentFlag columnAlignment (int column) const
 Returns the content alignment for a column.
AlignmentFlag headerAlignment (int column) const
 Returns the header alignment for a column.
void setColumnBorder (const WColor &color)
 Setss the column border color.
void setImagePack (const std::string &uri)
 Setss the base urls for icons.
std::string imagePack () const
 Returns the base url for icons.
void setExpanded (const WModelIndex &, bool expanded)
 Expand or collapse a node.
bool isExpanded (const WModelIndex &index) const
 Returns whether a node is expanded.
void collapse (const WModelIndex &index)
 Collapse a node.
void expand (const WModelIndex &index)
 Expand a node.
void expandToDepth (int depth)
 Expand all nodes to a depth.
void setAlternatingRowColors (bool enable)
 Sets if alternating row colors are to be used.
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 sortByColumn (int column, SortOrder order)
 Sort the data according to a column.
void setSortingEnabled (bool enabled)
 Enable sorting.
void setSortingEnabled (int column, bool enabled)
 Enable sorting.
bool isSortingEnabled () const
 Returns whether sorting is enabled.
void setColumnResizeEnabled (bool enabled)
 Enable interactive column resizing.
bool isColumnResizeEnabled () const
 Returns whether column resizing is enabled.
void setSelectionBehavior (SelectionBehavior behavior)
 Change the selection behaviour.
SelectionBehavior selectionBehavior () const
 Returns the selection behaviour.
void setSelectionMode (SelectionMode mode)
 Sets the selection mode.
SelectionMode selectionMode () const
 Returns the selection mode.
WItemSelectionModelselectionModel () const
 Returns the selection model.
void setSelectedIndexes (const WModelIndexSet &indexes)
 Sets the selected items.
void select (const WModelIndex &index, SelectionFlag option=Select)
 Select a single item.
bool isSelected (const WModelIndex &index) const
 Returns wheter an item is selected.
WModelIndexSet selectedIndexes () const
 Returns the set of selected items.
void setDragEnabled (bool enable)
 Enable the selection to be dragged (drag & drop).
void setDropsEnabled (bool enable)
 Enable drop operations (drag & drop).
void setColumn1Fixed (bool enable)
 Configure whether horizontal scrolling includes the first column.
virtual void resize (const WLength &width, const WLength &height)
 Resizes the widget.
virtual void load ()
 Load content just before the widget's content is rendered.
Signal< WModelIndex > & collapsed ()
 Signal emitted when a node is collapsed.
Signal< WModelIndex > & expanded ()
 Signal emitted when a node is expanded.
Signal< WModelIndex,
WMouseEvent > & 
clicked ()
 Signal emitted when an item is clicked.
Signal< WModelIndex,
WMouseEvent > & 
doubleClicked ()
 Signal emitted when an item is double clicked.
Signal< WModelIndex,
WMouseEvent > & 
mouseWentDown ()
 Signal emitted when an item is double clicked.
Signal< void > & selectionChanged ()
 Signal emitted when the selection is changed.
void setItemDelegate (WAbstractItemDelegate *delegate)
 Sets the default item delegate.
WAbstractItemDelegateitemDelegate () const
 Returns the default item delegate.
void setItemDelegateForColumn (int column, WAbstractItemDelegate *delegate)
 Sets the delegate for a column.
WAbstractItemDelegateitemDelegateForColumn (int column) const
 Returns the delegate for a column.
WAbstractItemDelegateitemDelegate (const WModelIndex &index) const
 Returns the delegate for rendering an item.
virtual void refresh ()
 Refresh the widget.

Protected Member Functions

virtual void dropEvent (const WDropEvent &event, const WModelIndex &target)
 Handle a drop event (drag & drop).
virtual WWidgetcreateExtraHeaderWidget (int column)
 Create an extra widget in the header.
WWidgetextraHeaderWidget (int column)
 Returns the extra header widget.
virtual void enableAjax ()
 Progress 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);

Member Function Documentation

void Wt::WTreeView::setModel ( WAbstractItemModel model  ) 

Sets the model.

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

When resetting a model, all nodes are initially collapsed, the selection is cleared, and the root index corresponds to the model's top level node (see setRootIndex()).

The initial model is 0.

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

See also:
setRootIndex()

WAbstractItemModel* Wt::WTreeView::model (  )  const [inline]

Returns the model.

See also:
setModel()

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()

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

Returns the root index.

See also:
setRootIndex()

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

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.

const WLength& Wt::WTreeView::headerHeight (  )  const [inline]

Returns the header height.

See also:
setHeaderHeight()

void Wt::WTreeView::setRowHeight ( const WLength rowHeight  ) 

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()

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.

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.

void Wt::WTreeView::setColumnWidth ( int  column,
const WLength width 
)

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()

WLength Wt::WTreeView::columnWidth ( int  column  )  const

Returns the column width.

See also:
setColumnWidth()

void Wt::WTreeView::setColumnAlignment ( int  column,
AlignmentFlag  alignment 
)

Sets the content alignment for a column.

The default value is AlignLeft.

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

void Wt::WTreeView::setHeaderAlignment ( int  column,
AlignmentFlag  alignment 
)

Sets the header alignment for a column.

The default value is AlignLeft.

See also:
setColumnAlignment()

AlignmentFlag Wt::WTreeView::columnAlignment ( int  column  )  const

Returns the content alignment for a column.

See also:
setColumnAlignment()

AlignmentFlag Wt::WTreeView::headerAlignment ( int  column  )  const

Returns the header alignment for a column.

See also:
setHeaderAlignment()

void Wt::WTreeView::setColumnBorder ( const WColor color  ) 

Setss the column border color.

The default border color is white.

void Wt::WTreeView::setImagePack ( const std::string &  uri  )  [inline]

Setss the base urls for icons.

This widget relies on several icons that are distributed together with Wt for drawing icons, lines, and backgrounds.

The default location for the image pack is resourcesURL.

The default value for resourcesURL is "resources/". This value may be overridden with a URL that points to a folder where these files are located, by configuring the resourcesURL property in your Wt configuration file.

std::string Wt::WTreeView::imagePack (  )  const [inline]

Returns the base url for icons.

See also:
setImagePack()

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

Expand or collapse a node.

See also:
expand(), collapse()

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

Returns whether a node is expanded.

See also:
setExpanded()

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

Collapse a node.

See also:
setExpanded(), expand()

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

Expand a node.

See also:
setExpanded(), collapse()

void Wt::WTreeView::expandToDepth ( int  depth  ) 

Expand 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()

void Wt::WTreeView::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:

stripe-30px.gif

Sample image use for alternating row colors

The image that is used is imagePack() + "/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()

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

Returns whether alternating row colors are used.

See also:
setAlternatingRowColors()

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

bool Wt::WTreeView::rootIsDecorated (  )  const [inline]

Returns whether toplevel items are decorated.

See also:
setRootIsDecorated()

void Wt::WTreeView::sortByColumn ( int  column,
SortOrder  order 
)

Sort the data according to a column.

Sorts the data according to data in column column and sort order order.

See also:
WAbstractItemModel::sort()

void Wt::WTreeView::setSortingEnabled ( bool  enabled  ) 

Enable sorting.

Enable or disable sorting by the user on all columns.

Sorting is enabled by default.

See also:
WAbstractItemModel::sort()

void Wt::WTreeView::setSortingEnabled ( int  column,
bool  enabled 
)

Enable sorting.

Enable or disable sorting by the user for a specific column.

Sorting is enabled by default.

See also:
WAbstractItemModel::sort()

bool Wt::WTreeView::isSortingEnabled (  )  const [inline]

Returns whether sorting is enabled.

See also:
setSortingEnabled()

void Wt::WTreeView::setColumnResizeEnabled ( bool  enabled  ) 

Enable interactive column resizing.

Enable or disable column resize handles for interactive resizing of the columns.

See also:
setColumnResizeEnabled()

bool Wt::WTreeView::isColumnResizeEnabled (  )  const [inline]

Returns whether column resizing is enabled.

See also:
setColumnResizeEnabled()

void Wt::WTreeView::setSelectionBehavior ( SelectionBehavior  behavior  ) 

Change the selection behaviour.

The selection behavior indicates whether whole rows or individual items can be selected. It is a property of the selectionModel().

By default, selection operates on rows (SelectRows), in which case model indexes will always be in the first column (column 0).

Alternatively, you can allow selection for individual items (SelectItems).

See also:
WItemSelectionModel::setSelectionBehavior(), setSelectionMode()

SelectionBehavior Wt::WTreeView::selectionBehavior (  )  const

Returns the selection behaviour.

See also:
setSelectionBehavior()

void Wt::WTreeView::setSelectionMode ( SelectionMode  mode  ) 

Sets the selection mode.

By default selection is disabled (NoSelection ).

See also:
setSelectionBehavior()

SelectionMode Wt::WTreeView::selectionMode (  )  const [inline]

Returns the selection mode.

See also:
setSelectionMode()

WItemSelectionModel* Wt::WTreeView::selectionModel (  )  const [inline]

Returns the selection model.

The selection model keeps track of the currently selected items.

void Wt::WTreeView::setSelectedIndexes ( const WModelIndexSet &  indexes  ) 

Sets the selected items.

Replaces the current selection with indexes.

See also:
select(), selectionModel()

void Wt::WTreeView::select ( const WModelIndex index,
SelectionFlag  option = Select 
)

Select a single item.

See also:
setSelectedIndexes(), selectionModel()

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

Returns wheter an item is selected.

This is a convenience method for:

 selectionModel()->isSelected(index)

See also:
selectedIndexes(), select(), selectionModel()

WModelIndexSet Wt::WTreeView::selectedIndexes (  )  const

Returns the set of selected items.

The model indexes are returned as a set, topologically ordered (in the order they appear in the view).

This is a convenience method for:

 selectionModel()->selectedIndexes()

See also:
setSelectedIndexes()

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

Enable the selection to be dragged (drag & drop).

To enable dragging of the selection, you first need to enable selection using setSelectionMode().

Whether an individual item may be dragged is controlled by the item's ItemIsDragEnabled flag. The selection can be dragged only if all items currently selected can be dragged.

See also:
setDropsEnabled()

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

Enable drop operations (drag & drop).

When drop is enabled, the tree view will indicate that something may be dropped when the mime-type of the dragged object is compatible with one of the model's accepted drop mime-types (see WAbstractItemModel::acceptDropMimeTypes()) or this widget's accepted drop mime-types (see WWidget::acceptDrops()), and the target item has drop enabled (which is controlled by the item's ItemIsDropEnabled flag).

Drop events must be handled in dropEvent().

See also:
setDragEnabled(), dropEvent()

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

Configure 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::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.

See also:
width(), height()

Reimplemented from Wt::WCompositeWidget.

virtual void Wt::WTreeView::load (  )  [virtual]

Load content just before the widget's content is rendered.

As soon as a widget is inserted into the widget hierarchy, it is rendered. Visible widgets are rendered immediately, and invisible widgets in the back-ground. This method is called when the widget is directly or indirectly inserted into the widget tree.

The default implementation simply propagates the load signal to its children. You may want to override this method to load resource-intensive content only when the widget is loaded into the browser.

Reimplemented from Wt::WCompositeWidget.

Signal<WModelIndex>& Wt::WTreeView::collapsed (  )  [inline]

Signal emitted when a node is collapsed.

See also:
setExpanded(), expanded()

Signal<WModelIndex>& Wt::WTreeView::expanded (  )  [inline]

Signal emitted when a node is expanded.

See also:
setExpanded(), collapsed()

Signal<WModelIndex, WMouseEvent>& Wt::WTreeView::clicked (  )  [inline]

Signal emitted when an item is clicked.

See also:
doubleClicked()

Signal<WModelIndex, WMouseEvent>& Wt::WTreeView::doubleClicked (  )  [inline]

Signal emitted when an item is double clicked.

See also:
doubleClicked()

Signal<WModelIndex, WMouseEvent>& Wt::WTreeView::mouseWentDown (  )  [inline]

Signal emitted when an item is double clicked.

See also:
doubleClicked()

Signal<void>& Wt::WTreeView::selectionChanged (  )  [inline]

Signal emitted when the selection is changed.

See also:
select(), setSelectionMode(), setSelectionBehavior()

void Wt::WTreeView::setItemDelegate ( WAbstractItemDelegate delegate  ) 

Sets the default item delegate.

The previous delegate is removed but not deleted.

The default item delegate is a WItemDelegate.

WAbstractItemDelegate* Wt::WTreeView::itemDelegate (  )  const [inline]

Returns the default item delegate.

See also:
setItemDelegate()

void Wt::WTreeView::setItemDelegateForColumn ( int  column,
WAbstractItemDelegate delegate 
)

Sets the delegate for a column.

The previous delegate is removed but not deleted.

See also:
setItemDelegate()

WAbstractItemDelegate* Wt::WTreeView::itemDelegateForColumn ( int  column  )  const

Returns the delegate for a column.

See also:
setItemDelegateForColumn()

WAbstractItemDelegate* Wt::WTreeView::itemDelegate ( const WModelIndex index  )  const

Returns the delegate for rendering an item.

See also:
setItemDelegateForColumn(), setItemDelegate()

virtual void Wt::WTreeView::refresh (  )  [virtual]

Refresh the widget.

The refresh method is invoked when the locale is changed using WApplication::setLocale() or when the user hit the refresh button.

The widget must actualize its contents in response.

Reimplemented from Wt::WCompositeWidget.

virtual void Wt::WTreeView::dropEvent ( const WDropEvent event,
const WModelIndex target 
) [protected, virtual]

Handle a drop event (drag & drop).

The event object contains details about the drop operation, identifying the source (which provides the data) and the mime-type of the data. The drop was received on the target item.

The drop event can be handled either by the view itself, or by the model. The default implementation checks if the mime-type is accepted by the model, and if so passes the drop event to the model. If the source is the view's own selection model, then the drop event will be handled as a MoveAction, otherwise the drop event will be handled as a CopyAction.

See also:
WAbstractItemModel::dropEvent()

virtual WWidget* Wt::WTreeView::createExtraHeaderWidget ( int  column  )  [protected, virtual]

Create an extra widget in the header.

You may reimplement this method to provide an extra widget to be placed below the header label. The extra widget will be visible only if a multi-line header is configured using setHeaderHeight().

The widget is created only once, but this method may be called repeatedly for a column for which prior calls returned 0 (i.e. each time the header is rerendered).

The default implementation returns 0.

See also:
setHeaderHeight(), extraHeaderWidget()

WWidget* Wt::WTreeView::extraHeaderWidget ( int  column  )  [protected]

Returns the extra header widget.

Returns the widget previously created using createExtraHeaderWidget()

See also:
createExtraHeaderWidget()

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

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


Generated on Tue Sep 1 17:51:17 2009 for Wt by doxygen 1.5.6