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::_GntTree::_GntTreeColInfo
struct  _GntTreeClass

Defines

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


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

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

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

void gnt_tree_adjust_columns ( GntTree *  tree  ) 

Automatically adjust the width of the columns in the tree.

Parameters:
tree The 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:
tree The tree
key The key for the row
colno The index of the column
text The new text

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

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

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.

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:
tree The tree
key The 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:
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

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.

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

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

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

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

int gnt_tree_get_visible_rows ( GntTree *  tree  ) 

Get the number visible rows.

Parameters:
tree The 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:
tree The 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:
columns Number 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:
tree The tree
key The key for the row to remove

void gnt_tree_remove_all ( GntTree *  tree  ) 

Remove all the item from the tree.

Parameters:
tree The tree

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.

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

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

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

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)

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)

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)

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

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

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)

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

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

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

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

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

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)

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)

void gnt_tree_set_selected ( GntTree *  tree,
void *  key 
)

Select a row.

Parameters:
tree The tree
key The key of the row to select

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

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

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

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