java-gnome version 4.0.15

org.gnome.gtk
Class TreeView

Object
  extended by org.freedesktop.bindings.Pointer
      extended by org.freedesktop.bindings.Proxy
          extended by org.gnome.glib.Object
              extended by org.gnome.gtk.Object
                  extended by org.gnome.gtk.Widget
                      extended by org.gnome.gtk.Container
                          extended by 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 TreeView.RowActivated 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 TreeSelection.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.RowActivated
          Emitted when a row in the TreeView has been activated.
static interface TreeView.RowExpanded
          Emitted when a row in the TreeView has been expanded, i.e. when its child nodes are shown.
static interface TreeView.SelectAll
          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.ButtonPressEvent, Widget.ButtonReleaseEvent, Widget.EnterNotifyEvent, Widget.ExposeEvent, Widget.FocusInEvent, Widget.FocusOutEvent, Widget.Hide, Widget.KeyPressEvent, Widget.KeyReleaseEvent, Widget.LeaveNotifyEvent, Widget.MapEvent, Widget.MotionNotifyEvent, Widget.PopupMenu, Widget.ScrollEvent, Widget.UnmapEvent, Widget.VisibilityNotifyEvent
 
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.RowActivated handler)
          Hook up a TreeView.RowActivated handler.
 void connect(TreeView.RowExpanded handler)
          Hook up a TreeView.RowExpanded handler.
 void connect(TreeView.SelectAll handler)
          Hook up a TreeView.SelectAll signal handler.
 void emitRowActivated(TreePath path, TreeViewColumn vertical)
          Cause a TreeView.RowActivated signal to be emitted for the given TreePath.
 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.
 TreeViewColumn getColumn(int index)
          Get the TreeViewColumn at the given position in the TreeView, with 0 being the left-most one.
 TreeViewColumn getColumnAtPos(int x, int y)
          Figure out which TreeViewColumn a given event's co-ordinates correspond to.
 TreeViewColumn[] getColumns()
          Get all the TreeViewColumns for this TreeView.
 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.
 TreePath getPathAtPos(int x, int y)
          Get a TreePath indicating what row in the TreeView a given set of co-ordinates corresponds to.
 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.
 void removeColumn(TreeViewColumn column)
          Remove a tree view column from 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 setCursor(TreePath path, TreeViewColumn vertical, boolean startEditing)
          Set the current keyboard focus to be at a specific path in the TreeView.
 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, addEvents, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, connect, getAllocation, getCanDefault, getCanFocus, getHasFocus, getName, getParent, getRequisition, getToplevel, getWindow, grabAdd, grabDefault, grabFocus, grabRemove, hide, modifyBackground, modifyBase, modifyFont, modifyText, queueDraw, queueDrawArea, setCanDefault, setCanFocus, setColormap, setEvents, setName, setSensitive, setSizeRequest, setTooltipMarkup, setTooltipText, show, showAll
 
Methods inherited from class org.freedesktop.bindings.Pointer
toString
 
Methods inherited from class 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.RowActivated handler)
Hook up a TreeView.RowActivated handler.


connect

public void connect(TreeView.RowExpanded handler)
Hook up a TreeView.RowExpanded handler.

Since:
4.0.7

connect

public void connect(TreeView.SelectAll handler)
Hook up a TreeView.SelectAll signal handler.


emitRowActivated

public void emitRowActivated(TreePath path,
                             TreeViewColumn vertical)
Cause a TreeView.RowActivated signal to be emitted for the given TreePath. The TreeViewColumn is optional; use null if you don't want to specify it.

Since:
4.0.9

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

getColumn

public TreeViewColumn getColumn(int index)
Get the TreeViewColumn at the given position in the TreeView, with 0 being the left-most one.

If they know they are going to need it later, most people just keep a reference to the TreeViewColumn around when they create it.

Since:
4.0.8

getColumnAtPos

public TreeViewColumn getColumnAtPos(int x,
                                     int y)
Figure out which TreeViewColumn a given event's co-ordinates correspond to. See getPathAtPos() for a detailed discussion.

In native GTK, this is implemented as an out parameter on the same function that powers getPathAtPos(), but we've given it a more coherent name here.

Since:
4.0.9

getColumns

public TreeViewColumn[] getColumns()
Get all the TreeViewColumns for this TreeView.

Since:
4.0.11

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.


getPathAtPos

public TreePath getPathAtPos(int x,
                             int y)
Get a TreePath indicating what row in the TreeView a given set of co-ordinates corresponds to.

The position indicated by (x,y) is in bin co-ordinates. Usually you are working in the context of a handler hooked up to an Event and these values should be obtained from that Event.

See also getColumnAtPos() for the complementary method to find out what vertical the co-ordinates correspond to.

Handling right-clicks

It is common to create a context menu as a result of a right-click on a TreeView. Ordinarily, you would intercept the Widget.ButtonPressEvent signal and then prepare your Menu in the handler there, quite reasonably expecting that the row that you have right-clicked on would be selected. Unfortunately, if you hook up to that signal your code will run before the default handler and the previously selected row will still be selected while your handler runs. This is annoying. It is the default Widget.ButtonPressEvent handler which selects the new row, so you have to manually select it yourself before acting on the right-click. It is getPathAtPos() which gives you the ability to do so:

 view.connect(new Widget.ButtonPressEvent() {
     public boolean onButtonPressEvent(Widget source, EventButton event) {
         final int x, y;
         final TreePath path;
         final TreeSelection selection;
 
         if (event.getButton() != MouseButton.RIGHT) {
             return false;
         }
 
         x = (int) event.getX();
         y = (int) event.getY();
         path = view.getPathAtPos(x, y);
 
         selection = view.getSelection();
         selection.selectRow(path);
 
         // and now pop your context menu, doing
         // something with the row as appropriate.
 
         return true;
     }
 });
 

Returns:
Will return null if the passed in co-ordinates do not correspond to a row in the TreeView.
Since:
4.0.9

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.


removeColumn

public void removeColumn(TreeViewColumn column)
Remove a tree view column from this TreeView.


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

setCursor

public void setCursor(TreePath path,
                      TreeViewColumn vertical,
                      boolean startEditing)
Set the current keyboard focus to be at a specific path in the TreeView. This method selects the row at path, and as a result is often used to draw a user's attention to a particular place.

If vertical is supplied, the specific TreeViewColumn indicated is selected. This is usually used in concert with setting startEditing to true which causes the TreeView to immediately start editing at the the specified row and column (assuming, of course, that that CellRenderer has been made mutable. See setEditable()).

Since:
4.0.8

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 TreeView.RowInserted and TreeView.RowDeleted.

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



java-gnome