org.gnome.gtk
Class TreeView

java.lang.Object
  org.freedesktop.bindings.Proxy
      org.gnome.glib.Object
          org.gnome.gtk.Object
              org.gnome.gtk.Widget
                  org.gnome.gtk.Container
                      org.gnome.gtk.TreeView

public class TreeView
extends Container

Display the data from a TreeModel in a tabular form. TreeViews are ubiquitous in most applications, being used to both output data in list form, as well as allowing the user to select one or more items from a list. TreeView is the view part of GTK's model-view-controller pattern list Widget, with one of the TreeModel subclasses supplying the underlying data model.

The TreeView API is very powerful, but with that power comes considerable complexity. To build a working TreeModel backed TreeView you will need to follow the instructions presented in the documentation quite carefully. The remainder of this page discusses the presentation side of the API; see DataColumn for a detailed overview of the contents side.

A TreeView is composed of one or more vertical columns called TreeViewColumns. Into these are packed CellRenderers. A CellRenderer does the job of taking data from the underlying TreeModel and rendering it in the TreeViewColumn. There is a family of CellRenderers for different underlying data types, but you'll use CellRendererText almost exclusively.

Let's assume we have a ListStore with a String DataColumn in it, ie

 final ListStore model;
 final DataColumnString countryNameColumn;
 final TreeView view;
 final TreeSelection selection;
 TreeViewColumn vertical;
 CellRendererText text;
 
 ...
 model = new ListStore(new DataColumn[] {
     countryNameColumn,
     ...
 }
 

Note that there is nothing that requires you to populate your model before building your TreeView. You can do that later - indeed, that might be the whole point of your application.

You start creating your view by instantiating a TreeView and then using it to get TreeViewColumn instances:

 view = new TreeView(model);
 vertical = view.appendColumn();
 vertical.setTitle("Country");
 

Now you construct a CellRenderer, specifying what TreeViewColumn it's going to be a part of, and then the most important part, specifying where its data is going to come from. This is the step that binds TreeView and TreeModel.

 text = new CellRendererText(vertical);
 text.setText(countryNameColumn);
 

along with setting any other properties on the CellRenderer as necessary. And that's it! You will of course need to do this for each TreeViewColumn of information you wish to have showing in your TreeView. (We tend to find it easier if you reuse the TreeViewColumn and CellRenderer variable names; there is usually no real reason to keep a reference to them individually; otherwise you've got to come up with unique names for everything and that tends to make for ugly code).

Dealing with the events generated on the TreeView is either straight forward or quite complicated, depending on what you are trying to accomplish. If you just need a callback when the user activates a row in the display, then the ROW_ACTIVATED signal will do the trick fairly simply; see its documentation for an example. For anything else, you will need to use the TreeSelection helper class (every TreeView automatically has one). It has a CHANGED signal which you hook up to which will tell you what row(s) are currently selected.

 selection = view.getSelection();
 

The design of the TreeView API is such that you can have more than one view for a given TreeModel, but we tend to only create TreeModels as the place to push the text that we wish displayed, so in general you'll have one TreeModel per TreeView.

We have departed a fair way from the method call sequence used in the underlying GTK library, in particular by assuming default behaviour and combining calls where possible. This is in an effort to make the TreeView API somewhat easier to learn, more appropriate in a Java context, and easier to use for the common cases which dominate its usage.

Since:

4.0.5

Author:

Andrew Cowie, Srichand Pendyala, Vreixo Formoso

Nested Class Summary

static interface	TreeView.ROW_ACTIVATED Emitted when a row in the TreeView has been activated.
static interface	TreeView.ROW_EXPANDED Emitted when a row in the TreeView has been expanded, i.e. when its child nodes are shown.
static interface	TreeView.SELECT_ALL This signal is emitted when the user selects all the rows in the TreeView.

Nested classes/interfaces inherited from class org.gnome.gtk.Widget

Widget.BUTTON_PRESS_EVENT, Widget.BUTTON_RELEASE_EVENT, Widget.ENTER_NOTIFY_EVENT, Widget.EXPOSE_EVENT, Widget.FOCUS_IN_EVENT, Widget.FOCUS_OUT_EVENT, Widget.HIDE, Widget.KEY_PRESS_EVENT, Widget.KEY_RELEASE_EVENT, Widget.LEAVE_NOTIFY_EVENT, Widget.UNMAP_EVENT, Widget.VISIBILITY_NOTIFY_EVENT

Constructor Summary

TreeView()
Construct a new TreeView.

TreeView(TreeModel store)
Construct a new TreeView with an already established TreeModel as its data.

Method Summary

TreeViewColumn	appendColumn() Create a new TreeViewColumn and add it to right-hand edge of this TreeView.
void	collapseAll() Collapse all the (child) rows in this TreeStore backed TreeView.
void	collapseRow(TreePath path) Collapse the given row, thus hiding its children if the row was previously expanded.
void	connect(TreeView.ROW_ACTIVATED handler) Hook up a ROW_ACTIVATED handler.
void	connect(TreeView.ROW_EXPANDED handler) Hook up a ROW_EXPANDED handler.
void	connect(TreeView.SELECT_ALL handler) Hook up a SELECT_ALL signal handler.
void	expandAll() Expand all the rows in this TreeStore backed TreeView, making all children visible.
boolean	expandRow(TreePath path, boolean openAll) Expand the given row, making its children visible to the user.
boolean	getEnableSearch() Check if the built-in quick search capability is enabled for this TreeView.
boolean	getFixedHeightMode() Get the current fixed height mode for the TreeView.
Adjustment	getHAdjustment() Get the Adjustment currently being used for the horizontal aspect of this TreeView.
TreeModel	getModel() Get the TreeModel currently providing the data powering this TreeView Widget, or null if not yet set.
boolean	getRubberBanding() Get the current status of the rubber banding property of the TreeView.
Entry	getSearchEntry() Get the current Entry widget being used for the interactive search feature for this TreeView.
TreeSelection	getSelection() Get the TreeSelection object corresponding to this TreeView.
Adjustment	getVAdjustment() Get the Adjustment for the vertical aspect of this TreeView.
boolean	rowExpanded(TreePath path) Check whether the given row is expanded, i.e. whether its children are shown.
void	scrollToCell(TreePath path, TreeViewColumn vertical) Scroll the TreeView so that the cell specified by path, vertical is visible.
void	scrollToCell(TreePath path, TreeViewColumn vertical, float rowAlign, float colAlign) Scroll the TreeView so that the cell specified by path, vertical is visible.
void	setEnableSearch(boolean setting) Set whether or not the built-in quick search capability will be enabled for this TreeView.
void	setFixedHeightMode(boolean enable) Set the fixed height mode for the TreeView.
void	setHAdjustment(Adjustment adjustment) Set the Adjustment for the horizontal aspect of this TreeView.
void	setHeadersClickable(boolean setting) Set whether the column titles in the header row can be clicked to change the sorting of the displayed data.
void	setHeadersVisible(boolean setting) Set whether this TreeView has a header row at the top of the Widget showing the titles of each of the TreeViewColumns packed into it.
void	setModel(TreeModel store) Set the TreeModel being used to source data for this TreeView.
void	setReorderable(boolean setting) Set whether the TreeModel being shown by this TreeView can be reordered by dragging and dropping the rows.
void	setRubberBanding(boolean enable) Set whether rubber banding is enabled in this TreeView.
void	setRulesHint(boolean setting) Request that alternating colours be drawn in the background of the TreeView.
void	setSearchColumn(DataColumn column) Set the column in your TreeModel which will searched through if the user starts an interactive search.
void	setSearchEntry(Entry entry) Set an Entry to be used as an alternative to the default built-in popup used by the the interactive search.
void	setVAdjustment(Adjustment adjustment) Set the Adjustment for the vertical aspect of this TreeView.

Methods inherited from class org.gnome.gtk.Container

add, getChildren, remove, setBorderWidth

Methods inherited from class org.gnome.gtk.Widget

activate, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, getAllocation, getHasFocus, getParent, getRequisition, getToplevel, getWindow, grabFocus, hide, modifyBackground, modifyText, setCanFocus, setSensitive, setSizeRequest, setTooltipMarkup, setTooltipText, show, showAll

Methods inherited from class org.freedesktop.bindings.Proxy

toString

Methods inherited from class java.lang.Object

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

Constructor Detail

TreeView

public TreeView()

Construct a new TreeView. If you use this constructor, you will need to call setModel() before any data will be displayable!

TreeView

public TreeView(TreeModel store)

Construct a new TreeView with an already established TreeModel as its data.

Method Detail

appendColumn

public TreeViewColumn appendColumn()

Create a new TreeViewColumn and add it to right-hand edge of this TreeView.

collapseAll

public void collapseAll()

Collapse all the (child) rows in this TreeStore backed TreeView. Only top level rows will be visible.

Since:

4.0.7

collapseRow

public void collapseRow(TreePath path)

Collapse the given row, thus hiding its children if the row was previously expanded.

Parameters:

path - The row to collapse.

Since:

4.0.7

connect

public void connect(TreeView.ROW_ACTIVATED handler)

Hook up a ROW_ACTIVATED handler.

connect

public void connect(TreeView.ROW_EXPANDED handler)

Hook up a ROW_EXPANDED handler.

Since:

4.0.7

connect

public void connect(TreeView.SELECT_ALL handler)

Hook up a SELECT_ALL signal handler.

expandAll

public void expandAll()

Expand all the rows in this TreeStore backed TreeView, making all children visible.

Since:

4.0.7

expandRow

public boolean expandRow(TreePath path,
                         boolean openAll)

Expand the given row, making its children visible to the user. This has no effect if the row has no child nodes. Of course, this is always the case if you use a ListStore model.

Parameters:

path - The row to expand.

openAll - true to recursively expand all children, false to expand only the given row.

Returns:

true if the path refers to a valid row, and it has child nodes. false otherwise.

Since:

4.0.7

getEnableSearch

public boolean getEnableSearch()

Check if the built-in quick search capability is enabled for this TreeView. The default is true.

Use setEnableSearch() to disable or enable the search feature.

Returns:

true if the quick search capability is enabled; false otherwise.

getFixedHeightMode

public boolean getFixedHeightMode()

Get the current fixed height mode for the TreeView. When set to true, all displayed rows in the TreeView are displayed with the same height.

To set the current height mode, see setFixedHeightMode()

Returns:

true if all rows are to be of the same height; false otherwise.

getHAdjustment

public Adjustment getHAdjustment()

Get the Adjustment currently being used for the horizontal aspect of this TreeView. If no horizontal adjustment is being used, then a null is returned. To set this value, see setHAdjustment().

getModel

public TreeModel getModel()

Get the TreeModel currently providing the data powering this TreeView Widget, or null if not yet set.

getRubberBanding

public boolean getRubberBanding()

Get the current status of the rubber banding property of the TreeView. See setRubberBanding() for a detailed description of how rubber banding works.

getSearchEntry

public Entry getSearchEntry()

Get the current Entry widget being used for the interactive search feature for this TreeView. If the built-in widget is being used for search, then null is returned.

getSelection

public TreeSelection getSelection()

Get the TreeSelection object corresponding to this TreeView. Every TreeView has a TreeSelection which is a utility instance allowing you to manipulate the state of the selected row(s) in the TreeView. This method gives you access to it.

getVAdjustment

public Adjustment getVAdjustment()

Get the Adjustment for the vertical aspect of this TreeView. If the vertical Adjustment has not been previously set, this value is null.

rowExpanded

public boolean rowExpanded(TreePath path)

Check whether the given row is expanded, i.e. whether its children are shown.

Parameters:

path - The row we want to check.

Returns:

true if the row is expanded, false if not.

Since:

4.0.7

scrollToCell

public void scrollToCell(TreePath path,
                         TreeViewColumn vertical)

Scroll the TreeView so that the cell specified by path, vertical is visible. This variant ignores alignment values and just scrolls the TreeView so that the cell specified is visible, closest to whichever edge it came in from, and doing nothing if the cell is already on screen.

See the discussion about path or vertical in the other scrollToCell() method to learn how you can scroll in a single direction only if desired.

Since:

4.0.6

scrollToCell

public void scrollToCell(TreePath path,
                         TreeViewColumn vertical,
                         float rowAlign,
                         float colAlign)

Scroll the TreeView so that the cell specified by path, vertical is visible.

Only one of path or vertical need to be specified if you only want to scroll in one dimension. If path is null, then it will only scroll horizontally; if no TreeViewColumn is specified in vertical (ie, likewise null), then only vertical scrolling will take place.

This all assumes that you've placed the TreeView is within a ScrolledWindow to enable scrolling behaviour!

Parameters:

rowAlign - Determines where in the view the row specified by path is placed, with 0.0f representing top, and 1.0f representing bottom, as usual. The constants in Alignment such as CENTER can be used.

colAlign - Determines where in the view the column specified by vertical will be placed; 0.0f is fully left, 1.0f is fully right.

Since:

4.0.6

setEnableSearch

public void setEnableSearch(boolean setting)

Set whether or not the built-in quick search capability will be enabled for this TreeView. If the user focuses the TreeView and starts typing characters a small popup Entry will appear and the characters entered will be used to interactively search through the list and will progressively select the row which is the closest match.

Use setSearchColumn() to indicate which data source in your TreeModel is actually what the interactive text search will seek through.

The default is true, so this method is only called when you wish to disable type-ahead find.

setFixedHeightMode

public void setFixedHeightMode(boolean enable)

Set the fixed height mode for the TreeView. When set to true, all displayed rows in the TreeView are displayed with the same height. This can have the effect of speeding up the TreeView, although you will have to evaluate this in the specific circumstances particular to your application.

To fetch the current height mode, see getFixedHeightMode().

Parameters:

enable - true if all rows in the TreeView are to be of the same height; false otherwise. The default is false.

setHAdjustment

public void setHAdjustment(Adjustment adjustment)

Set the Adjustment for the horizontal aspect of this TreeView. To fetch the current value of the horizontal adjustment aspect of this TreeView, use getHAdjustment().

setHeadersClickable

public void setHeadersClickable(boolean setting)

Set whether the column titles in the header row can be clicked to change the sorting of the displayed data. While the default is false (since you frequently have the rows ordered the way they are for a reason and don't want to let the user be reordering the display and getting lost in the process), calling TreeViewColumn's setSortColumn() will make the headers clickable. Use this method after your column setup to turn it off [again].

setHeadersVisible

public void setHeadersVisible(boolean setting)

Set whether this TreeView has a header row at the top of the Widget showing the titles of each of the TreeViewColumns packed into it. The default is true, for headers to be visible.

setModel

public void setModel(TreeModel store)

Set the TreeModel being used to source data for this TreeView. If a model has already been set, calling this will replace it.

Parameters:

store - a value of null will remove the data model underlying this TreeView, leaving it unset for the present.

setReorderable

public void setReorderable(boolean setting)

Set whether the TreeModel being shown by this TreeView can be reordered by dragging and dropping the rows. If this is turned on, no control is given over the ordering, so if you need to care about that you're probably going to need to manage drag and drop manually.

The default is false.

Incidentally, you can observe these changes by connecting to ROW_INSERTED and ROW_DELETED.

Since:

4.0.6

setRubberBanding

public void setRubberBanding(boolean enable)

Set whether rubber banding is enabled in this TreeView.

Rubber banding affects how selections work when the selection mode is set to MULTIPLE. When set to true then rubber banding will allow the user to select multiple rows with the mouse. Rubber banding is off by default.

setRulesHint

public void setRulesHint(boolean setting)

Request that alternating colours be drawn in the background of the TreeView. You call this to let the theme engine know that the user would really be helped in comprehending the data you are presenting if the rows were drawn with alternating background colours so as to emphasize the difference between each line. Most themes honour this request.

The default is false, not drawing alternating row colours.

setSearchColumn

public void setSearchColumn(DataColumn column)

Set the column in your TreeModel which will searched through if the user starts an interactive search. Ordinarily this can just be the DataColumnString of whichever column you want as the index, but if you have applied extensive formatting then you may need to supply an auxiliary column with the data in cleaner form (the use of DataColumnIntegers to provide sort order for verticals that are displaying formatting via setSortColumn() is analogous).

setSearchEntry

public void setSearchEntry(Entry entry)

Set an Entry to be used as an alternative to the default built-in popup used by the the interactive search. This is useful for occasions when you want to put the search Entry at some fixed location elsewhere in your UI.

To reset the TreeView to use the built-in popup Entry, pass in null.

setVAdjustment

public void setVAdjustment(Adjustment adjustment)

Set the Adjustment for the vertical aspect of this TreeView. To fetch the current vertical adjustment aspect of this TreeView, see getVAdjustment().