--- a/finch/libgnt/gnttree.h Sun Feb 02 02:27:03 2014 +0530
+++ b/finch/libgnt/gnttree.h Sun Feb 02 03:34:37 2014 +0530
@@ -102,11 +102,15 @@
G_BEGIN_DECLS
/**
+ * gnt_tree_get_gtype:
+ *
* Returns: The GType for GntTree
*/
GType gnt_tree_get_gtype(void);
/**
+ * gnt_tree_new:
+ *
* Create a tree with one column.
*
* Returns: The newly created tree
@@ -116,508 +120,562 @@
GntWidget * gnt_tree_new(void);
/**
- * Create a tree with a specified number of columns.
- *
+ * gnt_tree_new_with_columns:
* @columns: Number of columns
*
- * Returns: The newly created tree
+ * Create a tree with a specified number of columns.
*
* @see gnt_tree_new
+ *
+ * Returns: The newly created tree
*/
GntWidget * gnt_tree_new_with_columns(int columns);
/**
- * The number of rows the tree should display at a time.
- *
+ * gnt_tree_set_visible_rows:
* @tree: The tree
* @rows: The number of rows
+ *
+ * The number of rows the tree should display at a time.
*/
void gnt_tree_set_visible_rows(GntTree *tree, int rows);
/**
- * Get the number visible rows.
+ * gnt_tree_get_visible_rows:
+ * @tree: The tree
*
- * @tree: The tree
+ * Get the number visible rows.
*
* Returns: The number of visible rows
*/
int gnt_tree_get_visible_rows(GntTree *tree);
/**
- * Scroll the contents of the tree.
- *
+ * gnt_tree_scroll:
* @tree: The tree
* @count: If positive, the tree will be scrolled down by count rows,
* otherwise, it will be scrolled up by count rows.
+ *
+ * Scroll the contents of the tree.
*/
void gnt_tree_scroll(GntTree *tree, int count);
/**
- * Insert a row in the tree.
- *
+ * gnt_tree_add_row_after:
* @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
+ * Insert a row in the tree.
*
* @see gnt_tree_create_row
* @see gnt_tree_add_row_last
* @see gnt_tree_add_choice
+ *
+ * Returns: The inserted row
*/
GntTreeRow * gnt_tree_add_row_after(GntTree *tree, void *key, GntTreeRow *row, void *parent, void *bigbro);
/**
- * Insert a row at the end of the tree.
- *
+ * gnt_tree_add_row_last:
* @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
+ * Insert a row at the end of the tree.
*
* @see gnt_tree_create_row
* @see gnt_tree_add_row_after
* @see gnt_tree_add_choice
+ *
+ * Returns: The inserted row
*/
GntTreeRow * gnt_tree_add_row_last(GntTree *tree, void *key, GntTreeRow *row, void *parent);
/**
- * Get the key for the selected row.
+ * gnt_tree_get_selection_data:
+ * @tree: The tree
*
- * @tree: The tree
+ * Get the key for the selected row.
*
* Returns: The key for the selected row
*/
gpointer gnt_tree_get_selection_data(GntTree *tree);
/**
- * Get the text displayed for the selected row.
- *
+ * gnt_tree_get_selection_text:
* @tree: The tree
*
- * Returns: The text, which needs to be freed by the caller
+ * Get the text displayed for the selected row.
+ *
* @see gnt_tree_get_row_text_list
* @see gnt_tree_get_selection_text_list
+ *
+ * Returns: The text, which needs to be freed by the caller
*/
char * gnt_tree_get_selection_text(GntTree *tree);
/**
- * Get a list of text for a row.
- *
+ * gnt_tree_get_row_text_list:
* @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.
*
+ * Get a list of text for a row.
+ *
+ * @see gnt_tree_get_selection_text_list
+ * @see gnt_tree_get_selection_text
+ *
* 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 gnt_tree_get_selection_text_list
- * @see gnt_tree_get_selection_text
*/
GList * gnt_tree_get_row_text_list(GntTree *tree, gpointer key);
/**
- * Get the key of a row.
- *
+ * gnt_tree_row_get_key:
* @tree: The tree
* @row: The GntTreeRow object
*
+ * Get the key of a row.
+ *
* Returns: The key of the row.
- * @since 2.8.0 (gnt), 2.7.2 (pidgin)
+ *
+ * Since: 2.8.0 (gnt), 2.7.2 (pidgin)
*/
gpointer gnt_tree_row_get_key(GntTree *tree, GntTreeRow *row);
/**
- * Get the next row.
- *
+ * gnt_tree_row_get_next:
* @tree: The tree
* @row: The GntTreeRow object
*
+ * Get the next row.
+ *
* Returns: The next row.
- * @since 2.8.0 (gnt), 2.7.2 (pidgin)
+ *
+ * Since: 2.8.0 (gnt), 2.7.2 (pidgin)
*/
GntTreeRow * gnt_tree_row_get_next(GntTree *tree, GntTreeRow *row);
/**
- * Get the previous row.
- *
+ * gnt_tree_row_get_prev:
* @tree: The tree
* @row: The GntTreeRow object
*
+ * Get the previous row.
+ *
* Returns: The previous row.
- * @since 2.8.0 (gnt), 2.7.2 (pidgin)
+ *
+ * Since: 2.8.0 (gnt), 2.7.2 (pidgin)
*/
GntTreeRow * gnt_tree_row_get_prev(GntTree *tree, GntTreeRow *row);
/**
- * Get the child row.
- *
+ * gnt_tree_row_get_child:
* @tree: The tree
* @row: The GntTreeRow object
*
+ * Get the child row.
+ *
* Returns: The child row.
- * @since 2.8.0 (gnt), 2.7.2 (pidgin)
+ *
+ * Since: 2.8.0 (gnt), 2.7.2 (pidgin)
*/
GntTreeRow * gnt_tree_row_get_child(GntTree *tree, GntTreeRow *row);
/**
- * Get the parent row.
- *
+ * gnt_tree_row_get_parent:
* @tree: The tree
* @row: The GntTreeRow object
*
+ * Get the parent row.
+ *
* Returns: The parent row.
- * @since 2.8.0 (gnt), 2.7.2 (pidgin)
+ *
+ * Since: 2.8.0 (gnt), 2.7.2 (pidgin)
*/
GntTreeRow * gnt_tree_row_get_parent(GntTree *tree, GntTreeRow *row);
/**
+ * gnt_tree_get_selection_text_list:
+ * @tree: The tree
+ *
* Get a list of text of the current row.
*
- * @tree: The tree
+ * @see gnt_tree_get_row_text_list
+ * @see gnt_tree_get_selection_text
*
* 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 gnt_tree_get_row_text_list
- * @see gnt_tree_get_selection_text
*/
GList * gnt_tree_get_selection_text_list(GntTree *tree);
/**
- * Returns the list of rows in the tree.
+ * gnt_tree_get_rows:
+ * @tree: The tree
*
- * @tree: The tree
+ * Returns the list of rows in the tree.
*
* Returns: The list of the rows. The list should not be modified by the caller.
*/
GList *gnt_tree_get_rows(GntTree *tree);
/**
- * Remove a row from the tree.
- *
+ * gnt_tree_remove:
* @tree: The tree
* @key: The key for the row to remove
+ *
+ * Remove a row from the tree.
*/
void gnt_tree_remove(GntTree *tree, gpointer key);
/**
- * Remove all the item from the tree.
+ * gnt_tree_remove_all:
+ * @tree: The tree
*
- * @tree: The tree
+ * Remove all the item from the tree.
*/
void gnt_tree_remove_all(GntTree *tree);
/**
- * Get the visible line number of the selected row.
+ * gnt_tree_get_selection_visible_line:
+ * @tree: The tree
*
- * @tree: The tree
+ * Get the visible line number of the selected row.
*
* Returns: The line number of the currently selected row
*/
int gnt_tree_get_selection_visible_line(GntTree *tree);
/**
- * Change the text of a column in a row.
- *
+ * gnt_tree_change_text:
* @tree: The tree
* @key: The key for the row
* @colno: The index of the column
* @text: The new text
+ *
+ * Change the text of a column in a row.
*/
void gnt_tree_change_text(GntTree *tree, gpointer key, int colno, const char *text);
/**
- * Add a checkable item in the tree.
- *
+ * gnt_tree_add_choice:
* @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.
+ * Add a checkable item in the tree.
*
* @see gnt_tree_create_row
* @see gnt_tree_create_row_from_list
* @see gnt_tree_add_row_last
* @see gnt_tree_add_row_after
+ *
+ * Returns: The row inserted.
*/
GntTreeRow * gnt_tree_add_choice(GntTree *tree, void *key, GntTreeRow *row, void *parent, void *bigbro);
/**
- * Set whether a checkable item is checked or not.
- *
+ * gnt_tree_set_choice:
* @tree: The tree
* @key: The key for the row
* @set: %TRUE if the item should be checked, %FALSE if not
+ *
+ * Set whether a checkable item is checked or not.
*/
void gnt_tree_set_choice(GntTree *tree, void *key, gboolean set);
/**
- * Return whether a row is selected or not, where the row is a checkable item.
- *
+ * gnt_tree_get_choice:
* @tree: The tree
* @key: The key for the row
*
+ * Return whether a row is selected or not, where the row is a checkable item.
+ *
* Returns: %TRUE if the row is checked, %FALSE otherwise.
*/
gboolean gnt_tree_get_choice(GntTree *tree, void *key);
/**
- * Set flags for the text in a row in the tree.
- *
+ * gnt_tree_set_row_flags:
* @tree: The tree
* @key: The key for the row
* @flags: The flags to set
+ *
+ * Set flags for the text in a row in the tree.
*/
void gnt_tree_set_row_flags(GntTree *tree, void *key, GntTextFormatFlags flags);
/**
- * Set color for the text in a row in the tree.
- *
+ * gnt_tree_set_row_color:
* @tree: The tree
* @key: The key for the row
* @color: The color
- * @since 2.4.0
+ *
+ * Set color for the text in a row in the tree.
+ *
+ * Since: 2.4.0
*/
void gnt_tree_set_row_color(GntTree *tree, void *key, int color);
/**
- * Select a row.
- *
+ * gnt_tree_set_selected:
* @tree: The tree
* @key: The key of the row to select
+ *
+ * Select a row.
*/
void gnt_tree_set_selected(GntTree *tree , void *key);
/**
- * Create a row to insert in the tree.
- *
+ * gnt_tree_create_row:
* @tree: The tree
* @...: A string for each column in the tree
*
- * Returns: The row
+ * Create a row to insert in the tree.
*
* @see gnt_tree_create_row_from_list
* @see gnt_tree_add_row_after
* @see gnt_tree_add_row_last
* @see gnt_tree_add_choice
+ *
+ * Returns: The row
*/
GntTreeRow * gnt_tree_create_row(GntTree *tree, ...);
/**
- * Create a row from a list of text.
- *
+ * gnt_tree_create_row_from_list:
* @tree: The tree
* @list: The list containing the text for each column
*
- * Returns: The row
+ * Create a row from a list of text.
*
* @see gnt_tree_create_row
* @see gnt_tree_add_row_after
* @see gnt_tree_add_row_last
* @see gnt_tree_add_choice
+ *
+ * Returns: The row
*/
GntTreeRow * gnt_tree_create_row_from_list(GntTree *tree, GList *list);
/**
- * Set the width of a column in the tree.
- *
+ * gnt_tree_set_col_width:
* @tree: The tree
* @col: The index of the column
* @width: The width for the column
*
+ * Set the width of a column in the tree.
+ *
* @see gnt_tree_set_column_width_ratio
* @see gnt_tree_set_column_resizable
*/
void gnt_tree_set_col_width(GntTree *tree, int col, int width);
/**
- * Set the title for a column.
- *
+ * gnt_tree_set_column_title:
* @tree: The tree
* @index: The index of the column
* @title: The title for the column
*
+ * Set the title for a column.
+ *
* @see gnt_tree_set_column_titles
* @see gnt_tree_set_show_title
*
- * @since 2.0.0 (gnt), 2.1.0 (pidgin)
+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
*/
void gnt_tree_set_column_title(GntTree *tree, int index, const char *title);
/**
- * Set the titles of the columns
- *
+ * gnt_tree_set_column_titles:
* @tree: The tree
* @...: One title for each column in the tree
*
+ * Set the titles of the columns
+ *
* @see gnt_tree_set_column_title
* @see gnt_tree_set_show_title
*/
void gnt_tree_set_column_titles(GntTree *tree, ...);
/**
- * Set whether to display the title of the columns.
- *
+ * gnt_tree_set_show_title:
* @tree: The tree
* @set: If %TRUE, the column titles are displayed
*
+ * Set whether to display the title of the columns.
+ *
* @see gnt_tree_set_column_title
* @see gnt_tree_set_column_titles
*/
void gnt_tree_set_show_title(GntTree *tree, gboolean set);
/**
- * Set the compare function for sorting the data.
- *
+ * gnt_tree_set_compare_func:
* @tree: The tree
* @func: The comparison function, which is used to compare
* the keys
*
+ * Set the compare function for sorting the data.
+ *
* @see gnt_tree_sort_row
*/
void gnt_tree_set_compare_func(GntTree *tree, GCompareFunc func);
/**
- * Set whether a row, which has child rows, should be expanded.
- *
+ * gnt_tree_set_expanded:
* @tree: The tree
* @key: The key of the row
* @expanded: Whether to expand the child rows
+ *
+ * Set whether a row, which has child rows, should be expanded.
*/
void gnt_tree_set_expanded(GntTree *tree, void *key, gboolean expanded);
/**
- * Set whether to show column separators.
- *
+ * gnt_tree_set_show_separator:
* @tree: The tree
* @set: If %TRUE, the column separators are displayed
+ *
+ * Set whether to show column separators.
*/
void gnt_tree_set_show_separator(GntTree *tree, gboolean set);
/**
- * Sort a row in the tree.
- *
+ * gnt_tree_sort_row:
* @tree: The tree
* @row: The row to sort
*
+ * Sort a row in the tree.
+ *
* @see gnt_tree_set_compare_func
*/
void gnt_tree_sort_row(GntTree *tree, void *row);
/**
- * Automatically adjust the width of the columns in the tree.
+ * gnt_tree_adjust_columns:
+ * @tree: The tree
*
- * @tree: The tree
+ * Automatically adjust the width of the columns in the tree.
*/
void gnt_tree_adjust_columns(GntTree *tree);
/**
- * Set the hash functions to use to hash, compare and free the keys.
- *
+ * gnt_tree_set_hash_fns:
* @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
+ *
+ * Set the hash functions to use to hash, compare and free the keys.
*/
void gnt_tree_set_hash_fns(GntTree *tree, gpointer hash, gpointer eq, gpointer kd);
/**
+ * gnt_tree_set_column_visible:
+ * @tree: The tree
+ * @col: The index of the column
+ * @vis: If %FALSE, the column will not be displayed
+ *
* 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.
- *
- * @tree: The tree
- * @col: The index of the column
- * @vis: If %FALSE, the column will not be displayed
*/
void gnt_tree_set_column_visible(GntTree *tree, int col, gboolean vis);
/**
- * Set whether a column can be resized to keep the same ratio when the
- * tree is resized.
- *
+ * gnt_tree_set_column_resizable:
* @tree: The tree
* @col: The index of the column
* @res: If %FALSE, the column will not be resized when the
* tree is resized
*
+ * Set whether a column can be resized to keep the same ratio when the
+ * tree is resized.
+ *
* @see gnt_tree_set_col_width
* @see gnt_tree_set_column_width_ratio
*
- * @since 2.0.0 (gnt), 2.1.0 (pidgin)
+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
*/
void gnt_tree_set_column_resizable(GntTree *tree, int col, gboolean res);
/**
- * 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.
- *
+ * gnt_tree_set_column_is_binary:
* @tree: The tree
* @col: The index of the column
* @bin: %TRUE if the data for the column is binary
+ *
+ * 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.
*/
void gnt_tree_set_column_is_binary(GntTree *tree, int col, gboolean bin);
/**
- * Set whether text in a column should be right-aligned.
- *
+ * gnt_tree_set_column_is_right_aligned:
* @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)
+ * Set whether text in a column should be right-aligned.
+ *
+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
*/
void gnt_tree_set_column_is_right_aligned(GntTree *tree, int col, gboolean right);
/**
- * Set column widths to use when calculating column widths after a tree
- * is resized.
- *
+ * gnt_tree_set_column_width_ratio:
* @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.
*
+ * Set column widths to use when calculating column widths after a tree
+ * is resized.
+ *
* @see gnt_tree_set_col_width
* @see gnt_tree_set_column_resizable
*
- * @since 2.0.0 (gnt), 2.1.0 (pidgin)
+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
*/
void gnt_tree_set_column_width_ratio(GntTree *tree, int cols[]);
/**
- * Set the column to use for typeahead searching.
- *
+ * gnt_tree_set_search_column:
* @tree: The tree
* @col: The index of the column
*
- * @since 2.0.0 (gnt), 2.1.0 (pidgin)
+ * Set the column to use for typeahead searching.
+ *
+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
*/
void gnt_tree_set_search_column(GntTree *tree, int col);
/**
+ * gnt_tree_is_searching:
+ * @tree: The tree
+ *
* Check whether the user is currently in the middle of a search.
*
- * @tree: The tree
* Returns: %TRUE if the user is searching, %FALSE otherwise.
*
- * @since 2.0.0 (gnt), 2.1.0 (pidgin)
+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
*/
gboolean gnt_tree_is_searching(GntTree *tree);
/**
- * Set a custom search function.
- *
+ * gnt_tree_set_search_function:
* @tree: The tree
* @func: The custom search function. The search function is
* sent the tree itself, the key of a row, the search
@@ -625,19 +683,23 @@
* If the function returns %TRUE, the row is dislayed,
* otherwise it's not.
*
- * @since 2.0.0 (gnt), 2.1.0 (pidgin)
+ * Set a custom search function.
+ *
+ * Since: 2.0.0 (gnt), 2.1.0 (pidgin)
*/
void gnt_tree_set_search_function(GntTree *tree,
gboolean (*func)(GntTree *tree, gpointer key, const char *search, const char *current));
/**
- * Get the parent key for a row.
- *
+ * gnt_tree_get_parent_key:
* @tree: The tree
* @key: The key for the row.
*
+ * Get the parent key for a row.
+ *
* Returns: The key of the parent row.
- * @since 2.4.0
+ *
+ * Since: 2.4.0
*/
gpointer gnt_tree_get_parent_key(GntTree *tree, gpointer key);
