gnttree.h File Reference
GNT (GLib Ncurses Toolkit)
`#include "gntwidget.h"`
`#include "gnt.h"`
`#include "gntcolors.h"`
`#include "gntkeys.h"`
`#include "gnttextview.h"`

Go to the source code of this file.

## Data Structures

struct | _GntTree
struct | _GntTree::_GntTreeColInfo
struct | _GntTreeClass

## Macros

#define | GNT_TYPE_TREE (gnt_tree_get_gtype())
#define | GNT_TREE(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), GNT_TYPE_TREE, GntTree))
#define | GNT_TREE_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), GNT_TYPE_TREE, GntTreeClass))
#define | GNT_IS_TREE(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), GNT_TYPE_TREE))
#define | GNT_IS_TREE_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), GNT_TYPE_TREE))
#define | GNT_TREE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), GNT_TYPE_TREE, GntTreeClass))

## Typedefs

typedef struct _GntTree | GntTree
typedef struct _GntTreePriv | GntTreePriv
typedef struct _GntTreeClass | GntTreeClass
typedef struct _GntTreeRow | GntTreeRow
typedef struct _GntTreeCol | GntTreeCol
typedef enum _GntTreeColumnFlag | GntTreeColumnFlag

## Enumerations

enum | _GntTreeColumnFlag { GNT_TREE_COLUMN_INVISIBLE = 1 << 0, GNT_TREE_COLUMN_FIXED_SIZE = 1 << 1, GNT_TREE_COLUMN_BINARY_DATA = 1 << 2, GNT_TREE_COLUMN_RIGHT_ALIGNED = 1 << 3 }

## Functions

G_BEGIN_DECLS GType | gnt_tree_get_gtype (void)
GntWidget * | gnt_tree_new (void)
| Create a tree with one column. More...
GntWidget * | gnt_tree_new_with_columns (int columns)
| Create a tree with a specified number of columns. More...
void | gnt_tree_set_visible_rows (GntTree *tree, int rows)
| The number of rows the tree should display at a time. More...
int | gnt_tree_get_visible_rows (GntTree *tree)
| Get the number visible rows. More...
void | gnt_tree_scroll (GntTree *tree, int count)
| Scroll the contents of the tree. More...
GntTreeRow * | gnt_tree_add_row_after (GntTree *tree, void *key, GntTreeRow *row, void *parent, void *bigbro)
| Insert a row in the tree. More...
GntTreeRow * | gnt_tree_add_row_last (GntTree *tree, void *key, GntTreeRow *row, void *parent)
| Insert a row at the end of the tree. More...
gpointer | gnt_tree_get_selection_data (GntTree *tree)
| Get the key for the selected row. More...
char * | gnt_tree_get_selection_text (GntTree *tree)
| Get the text displayed for the selected row. More...
GList * | gnt_tree_get_row_text_list (GntTree *tree, gpointer key)
| Get a list of text for a row. More...
gpointer | gnt_tree_row_get_key (GntTree *tree, GntTreeRow *row)
| Get the key of a row. More...
GntTreeRow * | gnt_tree_row_get_next (GntTree *tree, GntTreeRow *row)
| Get the next row. More...
GntTreeRow * | gnt_tree_row_get_prev (GntTree *tree, GntTreeRow *row)
| Get the previous row. More...
GntTreeRow * | gnt_tree_row_get_child (GntTree *tree, GntTreeRow *row)
| Get the child row. More...
GntTreeRow * | gnt_tree_row_get_parent (GntTree *tree, GntTreeRow *row)
| Get the parent row. More...
GList * | gnt_tree_get_selection_text_list (GntTree *tree)
| Get a list of text of the current row. More...
GList * | gnt_tree_get_rows (GntTree *tree)
| Returns the list of rows in the tree. More...
void | gnt_tree_remove (GntTree *tree, gpointer key)
| Remove a row from the tree. More...
void | gnt_tree_remove_all (GntTree *tree)
| Remove all the item from the tree. More...
int | gnt_tree_get_selection_visible_line (GntTree *tree)
| Get the visible line number of the selected row. More...
void | gnt_tree_change_text (GntTree *tree, gpointer key, int colno, const char *text)
| Change the text of a column in a row. More...
GntTreeRow * | gnt_tree_add_choice (GntTree *tree, void *key, GntTreeRow *row, void *parent, void *bigbro)
| Add a checkable item in the tree. More...
void | gnt_tree_set_choice (GntTree *tree, void *key, gboolean set)
| Set whether a checkable item is checked or not. More...
gboolean | gnt_tree_get_choice (GntTree *tree, void *key)
| Return whether a row is selected or not, where the row is a checkable item. More...
void | gnt_tree_set_row_flags (GntTree *tree, void *key, GntTextFormatFlags flags)
| Set flags for the text in a row in the tree. More...
void | gnt_tree_set_row_color (GntTree *tree, void *key, int color)
| Set color for the text in a row in the tree. More...
void | gnt_tree_set_selected (GntTree *tree, void *key)
| Select a row. More...
GntTreeRow * | gnt_tree_create_row (GntTree *tree,...)
| Create a row to insert in the tree. More...
GntTreeRow * | gnt_tree_create_row_from_list (GntTree *tree, GList *list)
| Create a row from a list of text. More...
void | gnt_tree_set_col_width (GntTree *tree, int col, int width)
| Set the width of a column in the tree. More...
void | gnt_tree_set_column_title (GntTree *tree, int index, const char *title)
| Set the title for a column. More...
void | gnt_tree_set_column_titles (GntTree *tree,...)
| Set the titles of the columns. More...
void | gnt_tree_set_show_title (GntTree *tree, gboolean set)
| Set whether to display the title of the columns. More...
void | gnt_tree_set_compare_func (GntTree *tree, GCompareFunc func)
| Set the compare function for sorting the data. More...
void | gnt_tree_set_expanded (GntTree *tree, void *key, gboolean expanded)
| Set whether a row, which has child rows, should be expanded. More...
void | gnt_tree_set_show_separator (GntTree *tree, gboolean set)
| Set whether to show column separators. More...
void | gnt_tree_sort_row (GntTree *tree, void *row)
| Sort a row in the tree. More...
void | gnt_tree_adjust_columns (GntTree *tree)
| Automatically adjust the width of the columns in the tree. More...
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. More...
void | gnt_tree_set_column_visible (GntTree *tree, int col, gboolean vis)
| Set whether a column is visible or not. More...
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. More...
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. More...
void | gnt_tree_set_column_is_right_aligned (GntTree *tree, int col, gboolean right)
| Set whether text in a column should be right-aligned. More...
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. More...
void | gnt_tree_set_search_column (GntTree *tree, int col)
| Set the column to use for typeahead searching. More...
gboolean | gnt_tree_is_searching (GntTree *tree)
| Check whether the user is currently in the middle of a search. More...
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. More...
gpointer | gnt_tree_get_parent_key (GntTree *tree, gpointer key)
| Get the parent key for a row. More...

## Detailed Description

Tree API

Definition in file gnttree.h.

## Function Documentation

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

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.

See also
  gnt_tree_create_row
  gnt_tree_create_row_from_list
  gnt_tree_add_row_last
  gnt_tree_add_row_after

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

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

See also
  gnt_tree_create_row
  gnt_tree_add_row_last
  gnt_tree_add_choice

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

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

See also
  gnt_tree_create_row
  gnt_tree_add_row_after
  gnt_tree_add_choice

## 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_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_create_row()

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

Create a row to insert in the tree.

Parameters

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

Returns
  The row

See also
  gnt_tree_create_row_from_list
  gnt_tree_add_row_after
  gnt_tree_add_row_last
  gnt_tree_add_choice

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

Parameters

  tree | The tree
  list | The list containing the text for each column

Returns
  The row

See also
  gnt_tree_create_row
  gnt_tree_add_row_after
  gnt_tree_add_row_last
  gnt_tree_add_choice

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

G_BEGIN_DECLS GType gnt_tree_get_gtype | ( | void |  | ) |

Returns
  The GType for GntTree

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

Since
  2.4.0

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

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.

See also
  gnt_tree_get_selection_text_list
  gnt_tree_get_selection_text

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

## 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

## gnt_tree_get_selection_text()

char* gnt_tree_get_selection_text | ( | GntTree * | tree | ) |

Get the text displayed for the selected row.

Parameters

  tree | The tree

Returns
  The text, which needs to be freed by the caller

See also
  gnt_tree_get_row_text_list
  gnt_tree_get_selection_text_list

## gnt_tree_get_selection_text_list()

GList* gnt_tree_get_selection_text_list | ( | GntTree * | tree | ) |

Get a list of text of the current row.

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.

See also
  gnt_tree_get_row_text_list
  gnt_tree_get_selection_text

## 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_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_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.0.0 (gnt), 2.1.0 (pidgin)

## gnt_tree_new()

GntWidget* gnt_tree_new | ( | void |  | ) |

Create a tree with one column.

Returns
  The newly created tree

See also
  gnt_tree_new_with_columns

## gnt_tree_new_with_columns()

GntWidget* gnt_tree_new_with_columns | ( | int | columns | ) |

Create a tree with a specified number of columns.

Parameters

  columns | Number of columns

Returns
  The newly created tree

See also
  gnt_tree_new

## 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_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.8.0 (gnt), 2.7.2 (pidgin)

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

Since
  2.8.0 (gnt), 2.7.2 (pidgin)

## 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.8.0 (gnt), 2.7.2 (pidgin)

## 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.8.0 (gnt), 2.7.2 (pidgin)

## 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.8.0 (gnt), 2.7.2 (pidgin)

## 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_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_set_col_width()

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

Set the width of a column in the tree.

Parameters

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

See also
  gnt_tree_set_column_width_ratio
  gnt_tree_set_column_resizable

## 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.0.0 (gnt), 2.1.0 (pidgin)

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

Parameters

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

See also
  gnt_tree_set_col_width
  gnt_tree_set_column_width_ratio

Since
  2.0.0 (gnt), 2.1.0 (pidgin)

## gnt_tree_set_column_title()

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

Set the title for a column.

Parameters

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

See also
  gnt_tree_set_column_titles
  gnt_tree_set_show_title

Since
  2.0.0 (gnt), 2.1.0 (pidgin)

## gnt_tree_set_column_titles()

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

Set the titles of the columns.

Parameters

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

See also
  gnt_tree_set_column_title
  gnt_tree_set_show_title

## 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_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.

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.

See also
  gnt_tree_set_col_width
  gnt_tree_set_column_resizable

Since
  2.0.0 (gnt), 2.1.0 (pidgin)

## gnt_tree_set_compare_func()

void gnt_tree_set_compare_func | ( | GntTree * | tree,
|  | GCompareFunc | func
| ) |  |

Set the compare function for sorting the data.

Parameters

  tree | The tree
  func | The comparison function, which is used to compare the keys

See also
  gnt_tree_sort_row

## 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_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_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_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_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.0.0 (gnt), 2.1.0 (pidgin)

## gnt_tree_set_search_function()

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

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.0.0 (gnt), 2.1.0 (pidgin)

## 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_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_set_show_title()

void gnt_tree_set_show_title | ( | GntTree * | tree,
|  | gboolean | set
| ) |  |

Set whether to display the title of the columns.

Parameters

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

See also
  gnt_tree_set_column_title
  gnt_tree_set_column_titles

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

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

Sort a row in the tree.

Parameters

  tree | The tree
  row | The row to sort

See also
  gnt_tree_set_compare_func