GntTree: GNT Reference Manual

## GntTree GntTree — A widget that shows a tree of items |

## Functions

GType | gnt_tree_get_gtype ()
GntWidget * | gnt_tree_new ()
GntWidget * | gnt_tree_new_with_columns ()
void | gnt_tree_set_visible_rows ()
int | gnt_tree_get_visible_rows ()
void | gnt_tree_scroll ()
GntTreeRow * | gnt_tree_add_row_after ()
GntTreeRow * | gnt_tree_add_row_last ()
gpointer | gnt_tree_get_selection_data ()
char * | gnt_tree_get_selection_text ()
GList * | gnt_tree_get_row_text_list ()
gpointer | gnt_tree_row_get_key ()
GntTreeRow * | gnt_tree_row_get_next ()
GntTreeRow * | gnt_tree_row_get_prev ()
GntTreeRow * | gnt_tree_row_get_child ()
GntTreeRow * | gnt_tree_row_get_parent ()
GList * | gnt_tree_get_selection_text_list ()
GList * | gnt_tree_get_rows ()
void | gnt_tree_remove ()
void | gnt_tree_remove_all ()
int | gnt_tree_get_selection_visible_line ()
void | gnt_tree_change_text ()
GntTreeRow * | gnt_tree_add_choice ()
void | gnt_tree_set_choice ()
gboolean | gnt_tree_get_choice ()
void | gnt_tree_set_row_flags ()
void | gnt_tree_set_row_color ()
void | gnt_tree_set_selected ()
GntTreeRow * | gnt_tree_create_row ()
GntTreeRow * | gnt_tree_create_row_from_list ()
void | gnt_tree_set_col_width ()
void | gnt_tree_set_column_title ()
void | gnt_tree_set_column_titles ()
void | gnt_tree_set_show_title ()
void | gnt_tree_set_compare_func ()
void | gnt_tree_set_expanded ()
void | gnt_tree_set_show_separator ()
void | gnt_tree_sort_row ()
void | gnt_tree_adjust_columns ()
void | gnt_tree_set_hash_fns ()
void | gnt_tree_set_column_visible ()
void | gnt_tree_set_column_resizable ()
void | gnt_tree_set_column_is_binary ()
void | gnt_tree_set_column_is_right_aligned ()
void | gnt_tree_set_column_width_ratio ()
void | gnt_tree_set_search_column ()
gboolean | gnt_tree_is_searching ()
void | gnt_tree_set_search_function ()
gpointer | gnt_tree_get_parent_key ()

## Types and Values

enum | GntTreeColumnFlag
struct | GntTree
| GntTreeCol
| GntTreePriv
| GntTreeRow

## Description

## Functions

### gnt_tree_get_gtype ()

    GType
    gnt_tree_get_gtype (void);

#### Returns

The GType for GntTree

### gnt_tree_new ()

    GntWidget *
    gnt_tree_new (void);

Create a tree with one column.

See `gnt_tree_new_with_columns()`.

#### Returns

The newly created tree

### gnt_tree_new_with_columns ()

    GntWidget *
    gnt_tree_new_with_columns (int columns);

Create a tree with a specified number of columns.

See `gnt_tree_new()`.

#### Parameters

columns | Number of columns |

#### Returns

The newly created tree

### gnt_tree_set_visible_rows ()

    void
    gnt_tree_set_visible_rows (GntTree *tree,
                               int rows);

The number of rows the tree should display at a time.

#### Parameters

tree | The tree |
rows | The number of rows |

### gnt_tree_get_visible_rows ()

    int
    gnt_tree_get_visible_rows (GntTree *tree);

Get the number visible rows.

#### Parameters

tree | The tree |

#### Returns

The number of visible rows

### gnt_tree_scroll ()

    void
    gnt_tree_scroll (GntTree *tree,
                     int count);

Scroll the contents of the tree.

#### Parameters

tree | The tree |
count | If positive, the tree will be scrolled down by count rows, otherwise, it will be scrolled up by count rows. |

### gnt_tree_add_row_after ()

    GntTreeRow *
    gnt_tree_add_row_after (GntTree *tree,
                            void *key,
                            GntTreeRow *row,
                            void *parent,
                            void *bigbro);

Insert a row in the tree.

See `gnt_tree_create_row()`, `gnt_tree_add_row_last()`, `gnt_tree_add_choice()`.

#### Parameters

tree | The tree |
key | The key for the row |
row | The row to insert |
parent | The key for the parent row |
bigbro | The key for the row to insert the new row after. |

#### Returns

The inserted row

### gnt_tree_add_row_last ()

    GntTreeRow *
    gnt_tree_add_row_last (GntTree *tree,
                           void *key,
                           GntTreeRow *row,
                           void *parent);

Insert a row at the end of the tree.

See `gnt_tree_create_row()`, `gnt_tree_add_row_after()`, `gnt_tree_add_choice()`.

#### Parameters

tree | The tree |
key | The key for the row |
row | The row to insert |
parent | The key for the parent row |

#### Returns

The inserted row

### gnt_tree_get_selection_data ()

    gpointer
    gnt_tree_get_selection_data (GntTree *tree);

Get the key for the selected row.

#### Parameters

tree | The tree |

#### Returns

The key for the selected row.

[transfer none]

### gnt_tree_get_selection_text ()

    char *
    gnt_tree_get_selection_text (GntTree *tree);

Get the text displayed for the selected row.

See `gnt_tree_get_row_text_list()`, `gnt_tree_get_selection_text_list()`.

#### Parameters

tree | The tree |

#### Returns

The text, which needs to be freed by the caller

### gnt_tree_get_row_text_list ()

    GList *
    gnt_tree_get_row_text_list (GntTree *tree,
                                gpointer key);

Get a list of text for a row.

See `gnt_tree_get_selection_text_list()`, `gnt_tree_get_selection_text()`.

#### Parameters

tree | The tree |
key | A key corresponding to the row in question. If key is `NULL`, the text list for the selected row will be returned. |

#### Returns

A list of texts of a row. The list and its data should be freed by the caller. The caller should make sure that if any column of the tree contains binary data, it's not freed.

[transfer container][element-type utf8]

### gnt_tree_row_get_key ()

    gpointer
    gnt_tree_row_get_key (GntTree *tree,
                          GntTreeRow *row);

Get the key of a row.

#### Parameters

tree | The tree |
row | The GntTreeRow object |

#### Returns

The key of the row.

[transfer none]

Since: 2.7.3

### gnt_tree_row_get_next ()

    GntTreeRow *
    gnt_tree_row_get_next (GntTree *tree,
                           GntTreeRow *row);

Get the next row.

#### Parameters

tree | The tree |
row | The GntTreeRow object |

#### Returns

The next row.

Since: 2.7.3

### gnt_tree_row_get_prev ()

    GntTreeRow *
    gnt_tree_row_get_prev (GntTree *tree,
                           GntTreeRow *row);

Get the previous row.

#### Parameters

tree | The tree |
row | The GntTreeRow object |

#### Returns

The previous row.

Since: 2.7.3

### gnt_tree_row_get_child ()

    GntTreeRow *
    gnt_tree_row_get_child (GntTree *tree,
                            GntTreeRow *row);

Get the child row.

#### Parameters

tree | The tree |
row | The GntTreeRow object |

#### Returns

The child row.

Since: 2.7.3

### gnt_tree_row_get_parent ()

    GntTreeRow *
    gnt_tree_row_get_parent (GntTree *tree,
                             GntTreeRow *row);

Get the parent row.

#### Parameters

tree | The tree |
row | The GntTreeRow object |

#### Returns

The parent row.

Since: 2.7.3

### gnt_tree_get_selection_text_list ()

    GList *
    gnt_tree_get_selection_text_list (GntTree *tree);

Get a list of text of the current row.

See `gnt_tree_get_row_text_list()`, `gnt_tree_get_selection_text()`.

#### Parameters

tree | The tree |

#### Returns

A list of texts of the currently selected row. The list and its data should be freed by the caller. The caller should make sure that if any column of the tree contains binary data, it's not freed.

[transfer container][element-type utf8]

### gnt_tree_get_rows ()

    GList *
    gnt_tree_get_rows (GntTree *tree);

Returns the list of rows in the tree.

#### Parameters

tree | The tree |

#### Returns

The list of the rows. The list should not be modified by the caller.

[transfer none][element-type Gnt.TreeRow]

### gnt_tree_remove ()

    void
    gnt_tree_remove (GntTree *tree,
                     gpointer key);

Remove a row from the tree.

#### Parameters

tree | The tree |
key | The key for the row to remove |

### gnt_tree_remove_all ()

    void
    gnt_tree_remove_all (GntTree *tree);

Remove all the item from the tree.

#### Parameters

tree | The tree |

### gnt_tree_get_selection_visible_line ()

    int
    gnt_tree_get_selection_visible_line (GntTree *tree);

Get the visible line number of the selected row.

#### Parameters

tree | The tree |

#### Returns

The line number of the currently selected row

### gnt_tree_change_text ()

    void
    gnt_tree_change_text (GntTree *tree,
                          gpointer key,
                          int colno,
                          const char *text);

Change the text of a column in a row.

#### Parameters

tree | The tree |
key | The key for the row |
colno | The index of the column |
text | The new text |

### gnt_tree_add_choice ()

    GntTreeRow *
    gnt_tree_add_choice (GntTree *tree,
                         void *key,
                         GntTreeRow *row,
                         void *parent,
                         void *bigbro);

Add a checkable item in the tree.

See `gnt_tree_create_row()`, `gnt_tree_create_row_from_list()`, `gnt_tree_add_row_last()`, `gnt_tree_add_row_after()`.

#### Parameters

tree | The tree |
key | The key for the row |
row | The row to add |
parent | The parent of the row, or `NULL` |
bigbro | The row to insert after, or `NULL` |

#### Returns

The row inserted.

### gnt_tree_set_choice ()

    void
    gnt_tree_set_choice (GntTree *tree,
                         void *key,
                         gboolean set);

Set whether a checkable item is checked or not.

#### Parameters

tree | The tree |
key | The key for the row |
set | `TRUE` if the item should be checked, `FALSE` if not |

### gnt_tree_get_choice ()

    gboolean
    gnt_tree_get_choice (GntTree *tree,
                         void *key);

Return whether a row is selected or not, where the row is a checkable item.

#### Parameters

tree | The tree |
key | The key for the row |

#### Returns

`TRUE` if the row is checked, `FALSE` otherwise.

### gnt_tree_set_row_flags ()

    void
    gnt_tree_set_row_flags (GntTree *tree,
                            void *key,
                            GntTextFormatFlags flags);

Set flags for the text in a row in the tree.

#### Parameters

tree | The tree |
key | The key for the row |
flags | The flags to set |

### gnt_tree_set_row_color ()

    void
    gnt_tree_set_row_color (GntTree *tree,
                            void *key,
                            int color);

Set color for the text in a row in the tree.

#### Parameters

tree | The tree |
key | The key for the row |
color | The color |

Since: 2.4.0

### gnt_tree_set_selected ()

    void
    gnt_tree_set_selected (GntTree *tree,
                           void *key);

Select a row.

#### Parameters

tree | The tree |
key | The key of the row to select |

### gnt_tree_create_row ()

    GntTreeRow *
    gnt_tree_create_row (GntTree *tree,
                         ...);

Create a row to insert in the tree.

See `gnt_tree_create_row_from_list()`, `gnt_tree_add_row_after()`, `gnt_tree_add_row_last()`, `gnt_tree_add_choice()`.

#### Parameters

tree | The tree |
... | A string for each column in the tree |

#### Returns

The row

### gnt_tree_create_row_from_list ()

    GntTreeRow *
    gnt_tree_create_row_from_list (GntTree *tree,
                                   GList *list);

Create a row from a list of text.

See `gnt_tree_create_row()`, `gnt_tree_add_row_after()`, `gnt_tree_add_row_last()`, `gnt_tree_add_choice()`.

#### Parameters

tree | The tree |
list | The list containing the text for each column. | [element-type utf8]

#### Returns

The row.

[transfer full]

### gnt_tree_set_col_width ()

    void
    gnt_tree_set_col_width (GntTree *tree,
                            int col,
                            int width);

Set the width of a column in the tree.

See `gnt_tree_set_column_width_ratio()`, `gnt_tree_set_column_resizable()`

#### Parameters

tree | The tree |
col | The index of the column |
width | The width for the column |

### gnt_tree_set_column_title ()

    void
    gnt_tree_set_column_title (GntTree *tree,
                               int index,
                               const char *title);

Set the title for a column.

See `gnt_tree_set_column_titles()`, `gnt_tree_set_show_title()`.

#### Parameters

tree | The tree |
index | The index of the column |
title | The title for the column |

Since: 2.1.0

### gnt_tree_set_column_titles ()

    void
    gnt_tree_set_column_titles (GntTree *tree,
                                ...);

Set the titles of the columns

See `gnt_tree_set_column_title()`, `gnt_tree_set_show_title()`.

#### Parameters

tree | The tree |
... | One title for each column in the tree |

### gnt_tree_set_show_title ()

    void
    gnt_tree_set_show_title (GntTree *tree,
                             gboolean set);

Set whether to display the title of the columns.

See `gnt_tree_set_column_title()`, `gnt_tree_set_column_titles()`.

#### Parameters

tree | The tree |
set | If `TRUE`, the column titles are displayed |

### gnt_tree_set_compare_func ()

    void
    gnt_tree_set_compare_func (GntTree *tree,
                               GCompareFunc func);

Set the compare function for sorting the data.

See `gnt_tree_sort_row()`.

#### Parameters

tree | The tree |
func | The comparison function, which is used to compare the keys. | [scope call]

### gnt_tree_set_expanded ()

    void
    gnt_tree_set_expanded (GntTree *tree,
                           void *key,
                           gboolean expanded);

Set whether a row, which has child rows, should be expanded.

#### Parameters

tree | The tree |
key | The key of the row |
expanded | Whether to expand the child rows |

### gnt_tree_set_show_separator ()

    void
    gnt_tree_set_show_separator (GntTree *tree,
                                 gboolean set);

Set whether to show column separators.

#### Parameters

tree | The tree |
set | If `TRUE`, the column separators are displayed |

### gnt_tree_sort_row ()

    void
    gnt_tree_sort_row (GntTree *tree,
                       void *row);

Sort a row in the tree.

See `gnt_tree_set_compare_func()`.

#### Parameters

tree | The tree |
row | The row to sort |

### gnt_tree_adjust_columns ()

    void
    gnt_tree_adjust_columns (GntTree *tree);

Automatically adjust the width of the columns in the tree.

#### Parameters

tree | The tree |

### gnt_tree_set_hash_fns ()

    void
    gnt_tree_set_hash_fns (GntTree *tree,
                           gpointer hash,
                           gpointer eq,
                           gpointer kd);

Set the hash functions to use to hash, compare and free the keys.

#### Parameters

tree | The tree |
hash | The hashing function |
eq | The function to compare keys |
kd | The function to use to free the keys when a row is removed from the tree |

### gnt_tree_set_column_visible ()

    void
    gnt_tree_set_column_visible (GntTree *tree,
                                 int col,
                                 gboolean vis);

Set whether a column is visible or not. This can be useful when, for example, we want to store some data which we don't want/need to display.

#### Parameters

tree | The tree |
col | The index of the column |
vis | If `FALSE`, the column will not be displayed |

### gnt_tree_set_column_resizable ()

    void
    gnt_tree_set_column_resizable (GntTree *tree,
                                   int col,
                                   gboolean res);

Set whether a column can be resized to keep the same ratio when the tree is resized.

See `gnt_tree_set_col_width()`, `gnt_tree_set_column_width_ratio()`.

#### Parameters

tree | The tree |
col | The index of the column |
res | If `FALSE`, the column will not be resized when the tree is resized |

Since: 2.1.0

### gnt_tree_set_column_is_binary ()

    void
    gnt_tree_set_column_is_binary (GntTree *tree,
                                   int col,
                                   gboolean bin);

Set whether data in a column should be considered as binary data, and not as strings. A column containing binary data will be display empty text.

#### Parameters

tree | The tree |
col | The index of the column |
bin | `TRUE` if the data for the column is binary |

### gnt_tree_set_column_is_right_aligned ()

    void
    gnt_tree_set_column_is_right_aligned (GntTree *tree,
                                          int col,
                                          gboolean right);

Set whether text in a column should be right-aligned.

#### Parameters

tree | The tree |
col | The index of the column |
right | `TRUE` if the text in the column should be right aligned |

Since: 2.1.0

### gnt_tree_set_column_width_ratio ()

    void
    gnt_tree_set_column_width_ratio (GntTree *tree,
                                     int cols[]);

Set column widths to use when calculating column widths after a tree is resized.

See `gnt_tree_set_col_width()`, `gnt_tree_set_column_resizable()`.

#### Parameters

tree | The tree |
cols | Array of widths. The width must have the same number of entries as the number of columns in the tree, or end with a negative value for a column-width. |

Since: 2.1.0

### gnt_tree_set_search_column ()

    void
    gnt_tree_set_search_column (GntTree *tree,
                                int col);

Set the column to use for typeahead searching.

#### Parameters

tree | The tree |
col | The index of the column |

Since: 2.1.0

### gnt_tree_is_searching ()

    gboolean
    gnt_tree_is_searching (GntTree *tree);

Check whether the user is currently in the middle of a search.

#### Parameters

tree | The tree |

#### Returns

`TRUE` if the user is searching, `FALSE` otherwise.

Since: 2.1.0

### gnt_tree_set_search_function ()

    void
    gnt_tree_set_search_function (GntTree *tree,
                                  gboolean (*func) (GntTree *tree, gpointer key, const char *search, const char *current));

Set a custom search function.

#### Parameters

tree | The tree |
func | The custom search function. The search function is sent the tree itself, the key of a row, the search string and the content of row in the search column. If the function returns `TRUE`, the row is dislayed, otherwise it's not. |

Since: 2.1.0

### gnt_tree_get_parent_key ()

    gpointer
    gnt_tree_get_parent_key (GntTree *tree,
                             gpointer key);

Get the parent key for a row.

#### Parameters

tree | The tree |
key | The key for the row. |

#### Returns

The key of the parent row.

[transfer none]

Since: 2.4.0

## Types and Values

### enum GntTreeColumnFlag

`GntTreeColumnFlag` has been deprecated since version 2.14.0 and should not be used in newly-written code.

This is an internal implementation detail.

#### Members

GNT_TREE_COLUMN_INVISIBLE |  |
GNT_TREE_COLUMN_FIXED_SIZE |  |
GNT_TREE_COLUMN_BINARY_DATA |  |
GNT_TREE_COLUMN_RIGHT_ALIGNED |  |

### struct GntTree

    struct GntTree {
    	GntWidget parent;

    	GntTreeRow *GNTSEAL(current);    /* current selection */

    	GntTreeRow *GNTSEAL(top);        /* The topmost visible item */
    	GntTreeRow *GNTSEAL(bottom);     /* The bottommost visible item */

    	GntTreeRow *GNTSEAL(root);       /* The root of all evil */

    	GList *GNTSEAL(list);            /* List of GntTreeRow s */
    	GHashTable *GNTSEAL(hash);       /* We need this for quickly referencing the rows */
    	guint (*GNTSEAL(hash_func))(gconstpointer);
    	gboolean (*GNTSEAL(hash_eq_func))(gconstpointer, gconstpointer);
    	GDestroyNotify GNTSEAL(key_destroy);
    	GDestroyNotify GNTSEAL(value_destroy);

    	int GNTSEAL(ncol);               /* No. of columns */
    	struct _GntTreeColInfo
    	{
    		int GNTSEAL(width);
    		char *GNTSEAL(title);
    		int GNTSEAL(width_ratio);
    		GntTreeColumnFlag GNTSEAL(flags);
    	} *GNTSEAL(columns);             /* Would a GList be better? */
    	gboolean GNTSEAL(show_title);
    	gboolean GNTSEAL(show_separator); /* Whether to show column separators */

    	struct _GntTreePriv *GNTSEAL(priv);
    };

Access to any fields is deprecated. See inline comments for replacements.

### GntTreeCol

    typedef struct _GntTreeCol GntTreeCol;

`GntTreeCol` has been deprecated since version 2.14.0 and should not be used in newly-written code.

This is an internal implementation detail.

### GntTreePriv

    typedef struct _GntTreePriv GntTreePriv;

`GntTreePriv` has been deprecated since version 2.14.0 and should not be used in newly-written code.

This is an internal implementation detail.

### GntTreeRow

    typedef struct _GntTreeRow GntTreeRow;