Data Structures | Macros | Typedefs | Enumerations | Functions
gnttree.h File Reference

Tree API. More...

#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)
 
GntWidgetgnt_tree_new (void)
 Create a tree with one column. More...
 
GntWidgetgnt_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

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

Add a checkable item in the tree.

Parameters
treeThe tree
keyThe key for the row
rowThe row to add
parentThe parent of the row, or NULL
bigbroThe 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
GntTreeRow* gnt_tree_add_row_after ( GntTree tree,
void *  key,
GntTreeRow *  row,
void *  parent,
void *  bigbro 
)

Insert a row in the tree.

Parameters
treeThe tree
keyThe key for the row
rowThe row to insert
parentThe key for the parent row
bigbroThe 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
GntTreeRow* gnt_tree_add_row_last ( GntTree tree,
void *  key,
GntTreeRow *  row,
void *  parent 
)

Insert a row at the end of the tree.

Parameters
treeThe tree
keyThe key for the row
rowThe row to insert
parentThe key for the parent row
Returns
The inserted row
See also
gnt_tree_create_row
gnt_tree_add_row_after
gnt_tree_add_choice
void gnt_tree_adjust_columns ( GntTree tree)

Automatically adjust the width of the columns in the tree.

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

Change the text of a column in a row.

Parameters
treeThe tree
keyThe key for the row
colnoThe index of the column
textThe new text
GntTreeRow* gnt_tree_create_row ( GntTree tree,
  ... 
)

Create a row to insert in the tree.

Parameters
treeThe 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
GntTreeRow* gnt_tree_create_row_from_list ( GntTree tree,
GList *  list 
)

Create a row from a list of text.

Parameters
treeThe tree
listThe 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
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
treeThe tree
keyThe key for the row
Returns
TRUE if the row is checked, FALSE otherwise.
G_BEGIN_DECLS GType gnt_tree_get_gtype ( void  )
Returns
The GType for GntTree
gpointer gnt_tree_get_parent_key ( GntTree tree,
gpointer  key 
)

Get the parent key for a row.

Parameters
treeThe tree
keyThe key for the row.
Returns
The key of the parent row.
Since
2.4.0
GList* gnt_tree_get_row_text_list ( GntTree tree,
gpointer  key 
)

Get a list of text for a row.

Parameters
treeThe tree
keyA 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
GList* gnt_tree_get_rows ( GntTree tree)

Returns the list of rows in the tree.

Parameters
treeThe tree
Returns
The list of the rows. The list should not be modified by the caller.
gpointer gnt_tree_get_selection_data ( GntTree tree)

Get the key for the selected row.

Parameters
treeThe tree
Returns
The key for the selected row
char* gnt_tree_get_selection_text ( GntTree tree)

Get the text displayed for the selected row.

Parameters
treeThe 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
GList* gnt_tree_get_selection_text_list ( GntTree tree)

Get a list of text of the current row.

Parameters
treeThe 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
int gnt_tree_get_selection_visible_line ( GntTree tree)

Get the visible line number of the selected row.

Parameters
treeThe tree
Returns
The line number of the currently selected row
int gnt_tree_get_visible_rows ( GntTree tree)

Get the number visible rows.

Parameters
treeThe tree
Returns
The number of visible rows
gboolean gnt_tree_is_searching ( GntTree tree)

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

Parameters
treeThe tree
Returns
TRUE if the user is searching, FALSE otherwise.
Since
2.0.0 (gnt), 2.1.0 (pidgin)
GntWidget* gnt_tree_new ( void  )

Create a tree with one column.

Returns
The newly created tree
See also
gnt_tree_new_with_columns
GntWidget* gnt_tree_new_with_columns ( int  columns)

Create a tree with a specified number of columns.

Parameters
columnsNumber of columns
Returns
The newly created tree
See also
gnt_tree_new
void gnt_tree_remove ( GntTree tree,
gpointer  key 
)

Remove a row from the tree.

Parameters
treeThe tree
keyThe key for the row to remove
void gnt_tree_remove_all ( GntTree tree)

Remove all the item from the tree.

Parameters
treeThe tree
GntTreeRow* gnt_tree_row_get_child ( GntTree tree,
GntTreeRow *  row 
)

Get the child row.

Parameters
treeThe tree
rowThe GntTreeRow object
Returns
The child row.
Since
2.8.0 (gnt), 2.7.2 (pidgin)
gpointer gnt_tree_row_get_key ( GntTree tree,
GntTreeRow *  row 
)

Get the key of a row.

Parameters
treeThe tree
rowThe GntTreeRow object
Returns
The key of the row.
Since
2.8.0 (gnt), 2.7.2 (pidgin)
GntTreeRow* gnt_tree_row_get_next ( GntTree tree,
GntTreeRow *  row 
)

Get the next row.

Parameters
treeThe tree
rowThe GntTreeRow object
Returns
The next row.
Since
2.8.0 (gnt), 2.7.2 (pidgin)
GntTreeRow* gnt_tree_row_get_parent ( GntTree tree,
GntTreeRow *  row 
)

Get the parent row.

Parameters
treeThe tree
rowThe GntTreeRow object
Returns
The parent row.
Since
2.8.0 (gnt), 2.7.2 (pidgin)
GntTreeRow* gnt_tree_row_get_prev ( GntTree tree,
GntTreeRow *  row 
)

Get the previous row.

Parameters
treeThe tree
rowThe GntTreeRow object
Returns
The previous row.
Since
2.8.0 (gnt), 2.7.2 (pidgin)
void gnt_tree_scroll ( GntTree tree,
int  count 
)

Scroll the contents of the tree.

Parameters
treeThe tree
countIf positive, the tree will be scrolled down by count rows, otherwise, it will be scrolled up by count rows.
void gnt_tree_set_choice ( GntTree tree,
void *  key,
gboolean  set 
)

Set whether a checkable item is checked or not.

Parameters
treeThe tree
keyThe key for the row
setTRUE if the item should be checked, FALSE if not
void gnt_tree_set_col_width ( GntTree tree,
int  col,
int  width 
)

Set the width of a column in the tree.

Parameters
treeThe tree
colThe index of the column
widthThe width for the column
See also
gnt_tree_set_column_width_ratio
gnt_tree_set_column_resizable
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
treeThe tree
colThe index of the column
binTRUE if the data for the column is binary
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
treeThe tree
colThe index of the column
rightTRUE if the text in the column should be right aligned
Since
2.0.0 (gnt), 2.1.0 (pidgin)
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
treeThe tree
colThe index of the column
resIf 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)
void gnt_tree_set_column_title ( GntTree tree,
int  index,
const char *  title 
)

Set the title for a column.

Parameters
treeThe tree
indexThe index of the column
titleThe 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)
void gnt_tree_set_column_titles ( GntTree tree,
  ... 
)

Set the titles of the columns.

Parameters
treeThe tree
...One title for each column in the tree
See also
gnt_tree_set_column_title
gnt_tree_set_show_title
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
treeThe tree
colThe index of the column
visIf FALSE, the column will not be displayed
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
treeThe tree
colsArray 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)
void gnt_tree_set_compare_func ( GntTree tree,
GCompareFunc  func 
)

Set the compare function for sorting the data.

Parameters
treeThe tree
funcThe comparison function, which is used to compare the keys
See also
gnt_tree_sort_row
void gnt_tree_set_expanded ( GntTree tree,
void *  key,
gboolean  expanded 
)

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

Parameters
treeThe tree
keyThe key of the row
expandedWhether to expand the child rows
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
treeThe tree
hashThe hashing function
eqThe function to compare keys
kdThe function to use to free the keys when a row is removed from the tree
void gnt_tree_set_row_color ( GntTree tree,
void *  key,
int  color 
)

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

Parameters
treeThe tree
keyThe key for the row
colorThe color
Since
2.4.0
void gnt_tree_set_row_flags ( GntTree tree,
void *  key,
GntTextFormatFlags  flags 
)

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

Parameters
treeThe tree
keyThe key for the row
flagsThe flags to set
void gnt_tree_set_search_column ( GntTree tree,
int  col 
)

Set the column to use for typeahead searching.

Parameters
treeThe tree
colThe index of the column
Since
2.0.0 (gnt), 2.1.0 (pidgin)
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
treeThe tree
funcThe 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)
void gnt_tree_set_selected ( GntTree tree,
void *  key 
)

Select a row.

Parameters
treeThe tree
keyThe key of the row to select
void gnt_tree_set_show_separator ( GntTree tree,
gboolean  set 
)

Set whether to show column separators.

Parameters
treeThe tree
setIf TRUE, the column separators are displayed
void gnt_tree_set_show_title ( GntTree tree,
gboolean  set 
)

Set whether to display the title of the columns.

Parameters
treeThe tree
setIf TRUE, the column titles are displayed
See also
gnt_tree_set_column_title
gnt_tree_set_column_titles
void gnt_tree_set_visible_rows ( GntTree tree,
int  rows 
)

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

Parameters
treeThe tree
rowsThe number of rows
void gnt_tree_sort_row ( GntTree tree,
void *  row 
)

Sort a row in the tree.

Parameters
treeThe tree
rowThe row to sort
See also
gnt_tree_set_compare_func