The TreeView object is a widget for displaying trees and lists. The sole
purpose of this widget is for displaying the data on the screen and setting
other parts of the view using the associated objects.
Gtk Tree and List Widgets Overview
The standard tree and list widgets in Gtk are very powerful, but somewhat
complex. For your convenience, the Java-Gnome project has derived a number of
simpler classes for common uses of these widgets.
SimpleList
If you choose not to use those, or your requirements are such that you cannot
use them, you will have to learn how to use the full objects.
There is only one widget which is placed in any applications to create trees,
lists and tables. This is the
TreeView
. An application can have any
number of treeviews and they can be placed as can normal widgets. The data
for the widget, and the method in which it is displayed is controlled by
other classes. Gtk has been designed so that any number of treeview widgets
can be linked to the same data store.
TreeViewColumn
s,
CellRenderer
s and
TreeSelection
s are created for each view,
so Views can use the same data store but have their own column layout, data
display within those columns (linked to any of the dataBlocks in the store);
and their own selections.
Models are used to store data. Data is stored in what could be considered a
table. There are a number of
DataColumn
s, which could be considered
as data columns (in fact, in the C version of gtk, they are always referred to
as columns; but this can get confused with TreeViewColumns which are quite a
different matter). These dataBlocks each store one type of data (String,
boolean, int, etc.). The 'rows' of the data table, or the individual records
in the data store are accessible using iterators called
TreeIter
s.
These are used extensively in many methods. Setting data involves getting an
iterator (usually be creating a new row) and then setting the value for each
of the dataBlocks. The ordering of these dataBlocks has absolutely no meaning -
you can decide exactly which blocks are used on screen by setting Attribute
mappings to the CellRenderers which render data on the screen (see below).
Currently, there are two implementations of
TreeModel
ListStore
- This is used for tables and lists. Data is organised in
rows and columns.
TreeStore
- This is for the hierarchical trees. Data is organised
using
TreePath
's.
Both trees and lists can have multiple columns of data. Columns are added and
removed using the
TreeView
class. Columns are objects which determine
how the data is displayed. They have settings such as the column title,
whether the column can be resized, and even whether the columns can be
reorganized (by dragging the columns). Each
TreeView
widget has it's
own set of columns. Determining how the data is displayed in the columns is
done by CellRenderers (see below). Any number of renderers can be added to
the same column
Tree and list `cells' may contain a large variety of data types. Determining
how they are displayed is done by the CellRenderer family of classes. If the
data is unusual, or you want to combine a number of data types in a single
column, you may construct your own renderer. However, you are recommended to
stick with the regular choices:
CellRendererPixbuf
CellRendererText
CellRendererToggle
The CellRenderer's need data to be able to display. This is set using the
TreeViewColumn.addAttributeMapping(CellRenderer,CellRendererAttribute,DataColumn)
. The renderer attributes vary with each
renderer, for example CellRendererText has a TEXT attribute for the text the
be displayed. The final parameter is for the dataBlock in the store in which
the data is contained.
Java-Gnome comes with a number of simple example applications involving
trees. They may be useful for learning the functionality of these classes.
activateCell
public void activateCell(TreePath path,
TreeViewColumn column)
Activates the cell determined by path and column.
path
- The TreePath to be activated.column
- The TreeViewColumn to be activated.
addListener
public void addListener(TreeViewListener listener)
Register an object to handle button events.
appendColumn
public int appendColumn(TreeViewColumn column)
Appends column to the list of columns.
column
- The GtkTreeViewColumn to add.
- The number of columns in tree_view after appending.
appendDataColumn
public TreeViewColumn appendDataColumn(TreeViewColumn aExistingCol,
int aCol)
Appends a data column of the model to an existing
TreeViewColumn
, previously created with one of the
showDataColumn
methods. It should be used when it's
desired to have more than one data in just one column.
This method will try to guess the renderer to use, and because of that,
it has some limitations. For instance, you should only use it to show
these kinds of DataColumns:
DataColumnBoolean
,
DataColumnString
,
DataColumnPixbuf
,
DataColumnStockItem
.
For other kinds of DataColumn, the method
appendDataColumn(TreeViewColumn, int, CellRenderer, CellRendererAttribute)
should be used, which is more flexible, allowing you to specify which
renderer to use, and its rendering attributes.
aExistingCol
- an existing TreeViewColumn
.aCol
- the number of the column in the model to be shown; starting
from 0.
- an instance to the updated column.
appendDataColumn
public TreeViewColumn appendDataColumn(TreeViewColumn aExistingCol,
int aCol,
boolean expand)
Appends a data column of the model to an existing
TreeViewColumn
, previously created with one of the
showDataColumn
methods. It should be used when it's
desired to have more than one data in just one column.
This method will try to guess the renderer to use, and because of that,
it has some limitations. For instance, you should only use it to show
these kinds of DataColumns:
DataColumnBoolean
,
DataColumnString
,
DataColumnPixbuf
,
DataColumnStockItem
.
For other kinds of DataColumn, the method
appendDataColumn(TreeViewColumn, int, CellRenderer, CellRendererAttribute)
should be used, which is more flexible, allowing you to specify which
renderer to use, and its rendering attributes.
aExistingCol
- an existing TreeViewColumn
.aCol
- the number of the column in the model to be shown; starting
from 0.expand
- true
if this column should expand to fill the
available space in the row, false
otherwise.
- an instance to the updated column.
appendDataColumn
public TreeViewColumn appendDataColumn(TreeViewColumn aExistingCol,
int aCol,
CellRenderer aRenderer,
aAttr[] )
Appends a data column of the model to an existing
TreeViewColumn
, previously created with one of the
showDataColumn
methods, and lets you use a specific
renderer and rendering attributes.
It should be used when it's desired to have more than one data in just
one column.
aCol
- the number of the column in the model to be shown; starting
from 0.aRenderer
- the renderer to be used
- an instance to the updated column.
appendDataColumn
public TreeViewColumn appendDataColumn(TreeViewColumn aExistingCol,
int aCol,
CellRenderer aRenderer,
aAttr[] ,
boolean expand)
Appends a data column of the model to an existing
TreeViewColumn
, previously created with one of the
showDataColumn
methods, and lets you use a specific
renderer and rendering attributes.
It should be used when it's desired to have more than one data in just
one column.
aCol
- the number of the column in the model to be shown; starting
from 0.aRenderer
- the renderer to be usedexpand
- true
if this column should expand to fill the
available space in the row, false
otherwise.
- an instance to the updated column.
appendDataColumn
public TreeViewColumn appendDataColumn(TreeViewColumn aExistingCol,
int aCol,
CellRenderer aRenderer,
CellRendererAttribute aAttr)
Appends a data column of the model to an existing
TreeViewColumn
, previously created with one of the
showDataColumn
methods, and lets you use a specific
renderer and rendering attributes.
It should be used when it's desired to have more than one data in just
one column.
aCol
- the number of the column in the model to be shown; starting
from 0.aRenderer
- the renderer to be usedaAttr
- the rendering attributes to be used
- an instance to the updated column.
appendDataColumn
public TreeViewColumn appendDataColumn(TreeViewColumn aExistingCol,
int aCol,
CellRenderer aRenderer,
CellRendererAttribute aAttr,
boolean expand)
Appends a data column of the model to an existing
TreeViewColumn
, previously created with one of the
showDataColumn
methods, and lets you use a specific
renderer and rendering attributes.
It should be used when it's desired to have more than one data in just
one column.
aCol
- the number of the column in the model to be shown; starting
from 0.aRenderer
- the renderer to be usedaAttr
- the rendering attributes to be usedexpand
- true
if this column should expand to fill the
available space in the row, false
otherwise.
- an instance to the updated column.
autoSizeColumns
public void autoSizeColumns()
Resizes all columns to their optimal width. Only works after the treeview
has been realized.
collapseAll
public void collapseAll()
Recursively collapses all visible, expanded nodes.
collapseRow
public boolean collapseRow(TreePath path)
Collapses a row (hides its child rows, if they exist).
path
- Path to a row in the view
- TRUE if the row was collapsed.
expandAll
public void expandAll()
Recursively expands all nodes
expandRow
public boolean expandRow(TreePath path,
boolean openAll)
Opens the row so its children are visible.
path
- Path to a rowopenAll
- Whether to recursively expand, or just expand immediate
children
- TRUE if the row existed and had children
expandToPath
public void expandToPath(TreePath path)
Expands the row at path. This will also expand all parent rows of path as
necessary.
getAlternateRowColor
public boolean getAlternateRowColor()
getColumn
public TreeViewColumn getColumn(int position)
Gets the column at the given position in the tree view.
position
- The position of the column, counting from 0.
- The TreeViewColumn, or
null
if the position is
outside the range of columns.
getColumns
public TreeViewColumn[] getColumns()
Returns an array of all the columns currently in the view
getCursorColumn
public TreeViewColumn getCursorColumn()
Returns the current column
getCursorPath
public TreePath getCursorPath()
Returns the current path
getEnableSearch
public boolean getEnableSearch()
getFixedHeightMode
public boolean getFixedHeightMode()
Returns whether fixed height mode is turned on for this TreeView.
getHAdjustment
public Adjustment getHAdjustment()
Gets the GtkAdjustment currently being used for the horizontal aspect.
- A GtkAdjustment object, or NULL if none is currently being used.
getHeadersVisible
public boolean getHeadersVisible()
Returns true if the headers on the TreeView are visible.
getHoverExpand
public boolean getHoverExpand()
Returns whether hover expansion mode is turned on for TreeView.
getHoverSelection
public boolean getHoverSelection()
Returns whether hover selection mode is turned on for this TreeView.
getModel
public TreeModel getModel()
Returns the model associated with this tree.
getReorderable
public boolean getReorderable()
getRowExpanded
public boolean getRowExpanded(TreePath path)
Returns TRUE if the node pointed to by path is expanded.
path
- A TreePath to test expansion state.
- TRUE if path is expanded.
getRowSeparatorMethod
public TreeViewRowSeparatorMethod getRowSeparatorMethod()
Get the object which is used to determine whether a row should be drawn
as a separator.
- The TreeViewRowSeparatorMethod or null if
no method has been set.
getSearchDataColumn
public DataColumn getSearchDataColumn()
Gets the column searched on by the interactive search code.
- A DataColumn object representing the column of the data model in
which the interactive search takes place.
getSelection
public TreeSelection getSelection()
Gets the TreeSelection associated with this widget
getTreeView
public static TreeView getTreeView(Handle handle)
Creates a new tree view from a native handle
getType
public static Type getType()
Retrieve the runtime type used by the GLib library.
- getType in interface Container
getVAdjustment
public Adjustment getVAdjustment()
Gets the Adjustment currently being used for the vertical aspect.
insertColumn
public int insertColumn(TreeViewColumn column,
int position)
This inserts the column into the tree_view at position. If position is
-1, then the column is inserted at the end.
column
- The GtkTreeViewColumn to be inserted.position
- The position to insert column in.
- The number of columns in tree_view after insertion.
moveColumn
public void moveColumn(TreeViewColumn column,
TreeViewColumn baseColumn)
Moves column to be after to baseColumn. If baseColumn is NULL, then
column is placed in the first position.
column
- The GtkTreeViewColumn to be moved.baseColumn
- The GtkTreeViewColumn to be moved relative to, or NULL.
removeColumn
public int removeColumn(TreeViewColumn column)
Removes column from tree_view.
column
- The GtkTreeViewColumn to remove.
- The number of columns in tree_view after removing.
removeListener
public void removeListener(TreeViewListener listener)
Removes a listener
scrollToCell
public void scrollToCell(TreePath path)
Moves the alignments of the view to the position specified by path.
path
- The path of the row to move to, or NULL.
scrollToCell
public void scrollToCell(TreePath path,
TreeViewColumn column)
Moves the alignments of the view to the position specified by column and
path.
path
- The path of the row to move tocolumn
- The TreeViewColumn to move horizontally to
scrollToCell
public void scrollToCell(TreePath path,
TreeViewColumn column,
double rowAlign,
double colAlign)
Moves the alignments of the view to the position specified by column
and path. rowAlign determines where the row is
placed, and colAlign determines where column is placed. Both
are expected to be between 0.0 and 1.0. 0.0 means left/top alignment, 1.0
means right/bottom alignment, 0.5 means center.
path
- The path of the row to move tocolumn
- The TreeViewColumn to move horizontally torowAlign
- The vertical alignment of the row specified by path.colAlign
- :
The horizontal alignment of the column specified by column.
scrollToCell
public void scrollToCell(TreeViewColumn column)
Moves the alignments of the view to the position specified by column
column
- The TreeViewColumn to move horizontally to
scrollToPoint
public void scrollToPoint(int x,
int y)
Scrolls the TreeView such that the top-left corner of the visible area is
x, y, where x and y are specified in tree window coordinates. If either x
or y are -1 then that direction isn't scrolled.
setAlternateRowColor
public void setAlternateRowColor(boolean setting)
This function tells GTK+ that the user interface for your application
requires users to read across tree rows and associate cells with one
another. By default, GTK+ will then render the tree with alternating row
colors. Do not use it just because you prefer the appearance of the ruled
tree; that's a question for the theme. Some themes will draw tree rows in
alternating colors even when rules are turned off, and users who prefer
that appearance all the time can choose those themes. You should call
this function only as a semantic hint to the theme engine that your tree
makes alternating colors useful from a functional standpoint (since it
has lots of columns, generally).
setting
- TRUE if the tree requires reading across rows
setCursor
public void setCursor(TreePath path,
TreeViewColumn focusColumn,
boolean startEditing)
Sets the current keyboard focus to be at path, and selects it. This is
useful when you want to focus the user's attention on a particular row.
If column is specified, and startEditing is TRUE, then editing should be
started in the specified cell. This function is often followed by
Widget.grabFocus()
in order to give keyboard focus to the widget.
Please note that editing can only happen when the widget is realized.
path
- A TreePathfocusColumn
- A TreeViewColumn, or NULLstartEditing
- TRUE if the specified cell should start being edited.
setCursor
public void setCursor(TreePath path,
TreeViewColumn focusColumn,
CellRenderer focusCell,
boolean startEditing)
Sets the current keyboard focus to be at path, and selects it. This is
useful when you want to focus the user's attention on a particular row.
If column is specified, and startEditing is TRUE, then editing should be
started in the specified cell. If focusCell is also specified, the
particular cellRenderer in that column will get focusThis function is
often followed by
Widget.grabFocus()
in order to give keyboard
focus to the widget. Please note that editing can only happen when the
widget is realized.
path
- A TreePathfocusColumn
- A TreeViewColumn, or NULLfocusCell
- A cellrenderer, or nullstartEditing
- TRUE if the specified cell should start being edited.
setEnableSearch
public void setEnableSearch(boolean enableSearch)
If enable search is set, then the user can type in text to search through
the tree interactively.
enableSearch
- TRUE, if the user can search interactively
setExpanderColumn
public void setExpanderColumn(TreeViewColumn column)
Sets the column to draw the expander arrow at. If column is NULL, then
the expander arrow is always at the first visible column.
column
- NULL, or the column to draw the expander arrow at.
setFixedHeightMode
public void setFixedHeightMode(boolean enable)
Enables or disables the fixed height mode of this TreeView. Fixed height
mode speeds up TreeView by assuming that all rows have the same height.
Only enable this option if all rows are the same height and all columns
are of type
TreeViewColumnSizing.FIXED
.
enable
- TRUE to enable fixed height mode.
setHAdjustment
public void setHAdjustment(Adjustment hadj)
Sets the Adjustment for the current horizontal aspect.
setHeadersClickable
public void setHeadersClickable(boolean setting)
Allow the column title buttons to be clicked.
setting
- TRUE if the columns are clickable.
setHeadersVisible
public void setHeadersVisible(boolean headersVisible)
Sets the the visibility state of the headers.
headersVisible
- TRUE if the headers are visible
setHoverExpand
public void setHoverExpand(boolean expand)
Enables or disables the hover expansion mode of this TreeView. Hover
expansion makes rows expand or collapse if the pointer moves over them.
expand
- TRUE to enable hover selection mode.
setHoverSelection
public void setHoverSelection(boolean hover)
Enables of disables the hover selection mode of this TreeView. Hover
selection makes the selected row follow the pointer. Currently, this
works only for the selection modes
SelectionMode.SINGLE
and
SelectionMode.BROWSE
.
hover
- TRUE to enable hover selection mode.
setModel
public void setModel(TreeModel model)
Sets the model for a GtkTreeView. If the
TreeView
already has a
model set, it will remove it before setting the new model. If model is
NULL, then it will unset the old model.
setReorderable
public void setReorderable(boolean reorderable)
This function is a convenience function to allow you to reorder models
that support the DragSourceIface and the DragDestIface. Both
TreeStore
and
ListStore
support these. If reorderable is
TRUE, then the user can reorder the model by dragging and dropping rows.
The developer can listen to these changes by adding listeners.
This function does not give you any degree of control over the order --
any reorderering is allowed. If more control is needed, you should
probably handle drag and drop manually.
reorderable
- TRUE, if the tree can be reordered.
setRowSeparatorMethod
public void setRowSeparatorMethod(TreeViewRowSeparatorMethod method)
Set the object which is used to determine whether a row should be drawn
as a separator.
method
- The TreeViewRowSeparatorMethod or null
if no separators are to be drawn (the default).
setSearchDataColumn
public void setSearchDataColumn(DataColumn column)
Sets column as the column where the interactive search code should search
in. Additionally, turns on interactive searching.
column
- The column of the data model to search in.
setVAdjustment
public void setVAdjustment(Adjustment vadj)
Sets the Adjustment for the current vertical aspect.
showDataColumn
public TreeViewColumn showDataColumn(int aCol)
Shows a data column of the model in this
TreeView
. This
method will try to guess the renderer to use, and because of that, it has
some limitations. For instance, you should only use it to show these
kinds of DataColumns:
DataColumnBoolean
,
DataColumnString
,
DataColumnPixbuf
,
DataColumnStockItem
.
For other kinds of DataColumn, the method
showDataColumn(int, CellRenderer, CellRendererAttribute)
should be used, which is more flexible, allowing you to specify which
renderer to use, and its rendering attributes.
aCol
- the number of the column in the model to be shown; starting
from 0.
- an instance to the new shown column.
showDataColumn
public TreeViewColumn showDataColumn(int aCol,
boolean expand)
Shows a data column of the model in this
TreeView
. This
method will try to guess the renderer to use, and because of that, it has
some limitations. For instance, you should only use it to show these
kinds of DataColumns:
DataColumnBoolean
,
DataColumnString
,
DataColumnPixbuf
,
DataColumnStockItem
.
For other kinds of DataColumn, the method
showDataColumn(int, CellRenderer, CellRendererAttribute)
should be used, which is more flexible, allowing you to specify which
renderer to use, and its rendering attributes.
aCol
- the number of the column in the model to be shown; starting
from 0.expand
- true
if this column should expand to fill the
available space in the row, false
otherwise.
- an instance to the new shown column.
showDataColumn
public TreeViewColumn showDataColumn(int aCol,
CellRenderer aRenderer,
aAttr[] )
Shows a data column of the model in this TreeView
, with a
specific renderer and rendering attributes.
aCol
- the number of the column in the model to be shown; starting
from 0.aRenderer
- the renderer to be used
- an instance to the new shown column.
showDataColumn
public TreeViewColumn showDataColumn(int aCol,
CellRenderer aRenderer,
aAttr[] ,
boolean expand)
Shows a data column of the model in this TreeView
, with a
specific renderer and rendering attributes.
aCol
- the number of the column in the model to be shown; starting
from 0.aRenderer
- the renderer to be usedexpand
- true
if this column should expand to fill the
available space in the row, false
otherwise.
- an instance to the new shown column.
showDataColumn
public TreeViewColumn showDataColumn(int aCol,
CellRenderer aRenderer,
CellRendererAttribute aAttr)
Shows a data column of the model in this TreeView
, with a
specific renderer and rendering attributes.
aCol
- the number of the column in the model to be shown; starting
from 0.aRenderer
- the renderer to be usedaAttr
- the rendering attributes to be used
- an instance to the new shown column.
showDataColumn
public TreeViewColumn showDataColumn(int aCol,
CellRenderer aRenderer,
CellRendererAttribute aAttr,
boolean expand)
Shows a data column of the model in this TreeView
, with a
specific renderer and rendering attributes.
aCol
- the number of the column in the model to be shown; starting
from 0.aRenderer
- the renderer to be usedaAttr
- the rendering attributes to be usedexpand
- true
if this column should expand to fill the
available space in the row, false
otherwise.
- an instance to the new shown column.