changeset 18419:e79da0369a6d

Docs for GntTree.

--- a/finch/libgnt/gnttree.h	Mon Jul 02 23:19:30 2007 +0000
+++ b/finch/libgnt/gnttree.h	Tue Jul 03 01:50:16 2007 +0000
@@ -103,203 +103,253 @@
 G_BEGIN_DECLS
 
 /**
- * 
- *
- * @return
+ * @return The GType for GntTree
  */
 GType gnt_tree_get_gtype(void);
 
 /**
- * 
+ * Create a tree with one column.
  *
- * @return
+ * @return The newly created tree
+ *
+ * @see gnt_tree_new_with_columns
  */
 GntWidget * gnt_tree_new(void);
 
-      /* A tree with just one column */
-
 /**
- * 
- * @param columns
+ * Create a tree with a specified number of columns.
+ *
+ * @param columns  Number of columns
  *
- * @return
+ * @return  The newly created tree
+ *
+ * @see gnt_tree_new
  */
 GntWidget * gnt_tree_new_with_columns(int columns);
 
 /**
- * 
- * @param tree
- * @param rows
+ * The number of rows the tree should display at a time.
+ *
+ * @param tree  The tree
+ * @param rows  The number of rows
  */
 void gnt_tree_set_visible_rows(GntTree *tree, int rows);
 
 /**
- * 
- * @param tree
+ * Get the number visible rows.
  *
- * @return
+ * @param tree  The tree
+ *
+ * @return  The number of visible rows
  */
 int gnt_tree_get_visible_rows(GntTree *tree);
 
 /**
- * 
- * @param tree
- * @param count
+ * Scroll the contents of the tree.
+ *
+ * @param tree   The tree
+ * @param count  If positive, the tree will be scrolled down by count rows,
+ *               otherwise, it will be scrolled up by count rows.
  */
 void gnt_tree_scroll(GntTree *tree, int count);
 
 /**
- * 
- * @param tree
- * @param key
- * @param row
- * @param parent
- * @param bigbro
+ * Insert a row in the tree.
  *
- * @return
+ * @param tree    The tree
+ * @param key     The key for the row
+ * @param row     The row to insert
+ * @param parent  The key for the parent row
+ * @param bigbro  The key for the row to insert the new row after.
+ *
+ * @return  The inserted row
+ *
+ * @see gnt_tree_create_row
+ * @see gnt_tree_add_row_last
+ * @see gnt_tree_add_choice
  */
 GntTreeRow * gnt_tree_add_row_after(GntTree *tree, void *key, GntTreeRow *row, void *parent, void *bigbro);
 
 /**
- * 
- * @param tree
- * @param key
- * @param row
- * @param parent
+ * Insert a row at the end of the tree.
  *
- * @return
+ * @param tree    The tree
+ * @param key     The key for the row
+ * @param row     The row to insert
+ * @param parent  The key for the parent row
+ *
+ * @return The inserted row
+ *
+ * @see gnt_tree_create_row
+ * @see gnt_tree_add_row_after
+ * @see gnt_tree_add_choice
  */
 GntTreeRow * gnt_tree_add_row_last(GntTree *tree, void *key, GntTreeRow *row, void *parent);
 
 /**
- * 
- * @param tree
+ * Get the key for the selected row.
  *
- * @return
+ * @param tree  The tree
+ *
+ * @return   The key for the selected row
  */
 gpointer gnt_tree_get_selection_data(GntTree *tree);
 
-/* Returned string needs to be freed */
 /**
- * 
- * @param tree
+ * Get the text displayed for the selected row.
  *
- * @return
+ * @param tree  The tree
+ *
+ * @return  The text, which needs to be freed by the caller
  */
 char * gnt_tree_get_selection_text(GntTree *tree);
 
 /**
- * 
- * @param tree
+ * Get a list of text of the current row.
  *
- * @return
+ * @param tree  The tree
+ *
+ * @return A list of texts of the currently selected row. The list
+ *         and its data should be freed by the caller.
  */
 GList * gnt_tree_get_selection_text_list(GntTree *tree);
 
 /**
+ * Returns the list of rows in the tree.
  *
- * @param tree
+ * @param tree  The tree
  *
- * @constreturn
+ * @return The list of the rows. The list should not be modified by the caller.
  */
 GList *gnt_tree_get_rows(GntTree *tree);
 
 /**
- * 
- * @param tree
- * @param key
+ * Remove a row from the tree.
+ *
+ * @param tree  The tree
+ * @param key   The key for the row to remove
  */
 void gnt_tree_remove(GntTree *tree, gpointer key);
 
 /**
- * 
- * @param tree
+ * Remove all the item from the tree.
+ *
+ * @param tree  The tree
  */
 void gnt_tree_remove_all(GntTree *tree);
 
-/* Returns the visible line number of the selected row */
 /**
- * 
- * @param tree
+ * Get the visible line number of the selected row.
  *
- * @return
+ * @param tree  The tree
+ *
+ * @return  The line number of the currently selected row
  */
 int gnt_tree_get_selection_visible_line(GntTree *tree);
 
 /**
- * 
- * @param tree
- * @param key
- * @param colno
- * @param text
+ * Change the text of a column in a row.
+ *
+ * @param tree   The tree
+ * @param key    The key for the row
+ * @param colno  The index of the column
+ * @param text   The new text
  */
 void gnt_tree_change_text(GntTree *tree, gpointer key, int colno, const char *text);
 
 /**
- * 
- * @param tree
- * @param key
- * @param row
- * @param parent
- * @param bigbro
+ * Add a checkable item in the tree.
  *
- * @return
+ * @param tree    The tree
+ * @param key     The key for the row
+ * @param row     The row to add
+ * @param parent  The parent of the row, or @c NULL
+ * @param bigbro  The row to insert after, or @c NULL
+ *
+ * @return  The row inserted.
+ *
+ * @see gnt_tree_create_row
+ * @see gnt_tree_create_row_from_list
+ * @see gnt_tree_add_row_last
+ * @see gnt_tree_add_row_after
  */
 GntTreeRow * gnt_tree_add_choice(GntTree *tree, void *key, GntTreeRow *row, void *parent, void *bigbro);
 
 /**
- * 
- * @param tree
- * @param key
- * @param set
+ * Set whether a checkable item is checked or not.
+ *
+ * @param tree   The tree
+ * @param key    The key for the row
+ * @param set    @c TRUE if the item should be checked, @c FALSE if not
  */
 void gnt_tree_set_choice(GntTree *tree, void *key, gboolean set);
 
 /**
- * 
- * @param tree
- * @param key
+ * Return whether a row is selected or not, where the row is a checkable item.
  *
- * @return
+ * @param tree  The tree
+ * @param key   The key for the row
+ *
+ * @return    @c TRUE if the row is checked, @c FALSE otherwise.
  */
 gboolean gnt_tree_get_choice(GntTree *tree, void *key);
 
 /**
- * 
- * @param tree
- * @param key
- * @param flags
+ * Set flags for the text in a row in the tree.
+ *
+ * @param tree   The tree
+ * @param key    The key for the row
+ * @param flags  The flags to set
  */
 void gnt_tree_set_row_flags(GntTree *tree, void *key, GntTextFormatFlags flags);
 
 /**
- * 
- * @param key
+ * Select a row.
+ *
+ * @param tree  The tree
+ * @param key   The key of the row to select
  */
 void gnt_tree_set_selected(GntTree *tree , void *key);
 
 /**
- * 
- * @param tree
+ * Create a row to insert in the tree.
+ *
+ * @param tree The tree
+ * @param ...  A string for each column in the tree
  *
- * @return
+ * @return   The row
+ *
+ * @see gnt_tree_create_row_from_list
+ * @see gnt_tree_add_row_after
+ * @see gnt_tree_add_row_last
+ * @see gnt_tree_add_choice
  */
 GntTreeRow * gnt_tree_create_row(GntTree *tree, ...);
 
 /**
- * 
- * @param tree
- * @param list
+ * Create a row from a list of text.
+ *
+ * @param tree  The tree
+ * @param list  The list containing the text for each column
  *
- * @return
+ * @return   The row
+ *
+ * @see gnt_tree_create_row
+ * @see gnt_tree_add_row_after
+ * @see gnt_tree_add_row_last
+ * @see gnt_tree_add_choice
  */
 GntTreeRow * gnt_tree_create_row_from_list(GntTree *tree, GList *list);
 
 /**
- * 
- * @param tree
- * @param col
- * @param width
+ * Set the width of a column in the tree.
+ *
+ * @param tree   The tree
+ * @param col    The index of the column
+ * @param width  The width for the column
+ *
+ * @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);
 
@@ -309,64 +359,87 @@
  * @param tree   The tree
  * @param index  The index of the column
  * @param title  The title for the column
+ *
+ * @see gnt_tree_set_column_titles
+ * @see gnt_tree_set_show_title
  */
 void gnt_tree_set_column_title(GntTree *tree, int index, const char *title);
 
 /**
- * 
- * @param tree
+ * Set the titles of the columns
+ *
+ * @param tree  The tree
+ * @param ...   One title for each column in the tree
+ *
+ * @see gnt_tree_set_column_title
+ * @see gnt_tree_set_show_title
  */
 void gnt_tree_set_column_titles(GntTree *tree, ...);
 
 /**
- * 
- * @param tree
- * @param set
+ * Set whether to display the title of the columns.
+ *
+ * @param tree  The tree
+ * @param set   If @c TRUE, the column titles are displayed
+ *
+ * @see gnt_tree_set_column_title
+ * @see gnt_tree_set_column_titles
  */
 void gnt_tree_set_show_title(GntTree *tree, gboolean set);
 
 /**
- * 
- * @param tree
- * @param func
+ * Set the compare function for sorting the data.
+ *
+ * @param tree  The tree
+ * @param func  The comparison function, which is used to compare
+ *              the keys
+ *
+ * @see gnt_tree_sort_row 
  */
 void gnt_tree_set_compare_func(GntTree *tree, GCompareFunc func);
 
 /**
- * 
- * @param tree
- * @param key
- * @param expanded
+ * Set whether a row, which has child rows, should be expanded.
+ *
+ * @param tree      The tree
+ * @param key       The key of the row
+ * @param expanded  Whether to expand the child rows
  */
 void gnt_tree_set_expanded(GntTree *tree, void *key, gboolean expanded);
 
 /**
- * 
- * @param tree
- * @param set
+ * Set whether to show column separators.
+ *
+ * @param tree  The tree
+ * @param set   If @c TRUE, the column separators are displayed
  */
 void gnt_tree_set_show_separator(GntTree *tree, gboolean set);
 
 /**
- * 
- * @param tree
- * @param row
+ * Sort a row in the tree.
+ *
+ * @param tree  The tree
+ * @param row   The row to sort
+ *
+ * @see gnt_tree_set_compare_func
  */
 void gnt_tree_sort_row(GntTree *tree, void *row);
 
-/* This will try to automatically adjust the width of the columns in the tree */
 /**
- * 
- * @param tree
+ * Automatically adjust the width of the columns in the tree.
+ *
+ * @param tree  The tree
  */
 void gnt_tree_adjust_columns(GntTree *tree);
 
 /**
- * 
- * @param tree
- * @param hash
- * @param eq
- * @param kd
+ * Set the hash functions to use to hash, compare and free the keys.
+ *
+ * @param tree  The tree
+ * @param hash  The hashing function
+ * @param eq    The function to compare keys
+ * @param kd    The function to use to free the keys when a row is removed
+ *              from the tree
  */
 void gnt_tree_set_hash_fns(GntTree *tree, gpointer hash, gpointer eq, gpointer kd);
 
@@ -389,6 +462,9 @@
  * @param col   The index of the column
  * @param res   If @c FALSE, the column will not be resized when the
  *              tree is resized
+ *
+ * @see gnt_tree_set_col_width
+ * @see gnt_tree_set_column_width_ratio
  */
 void gnt_tree_set_column_resizable(GntTree *tree, int col, gboolean res);
 
@@ -400,6 +476,9 @@
  * @param 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 gnt_tree_set_col_width
+ * @see gnt_tree_set_column_resizable
  */
 void gnt_tree_set_column_width_ratio(GntTree *tree, int cols[]);
 
@@ -408,11 +487,6 @@
 /* The following functions should NOT be used by applications. */
 
 /* This should be called by the subclasses of GntTree's in their _new function */
-/**
- * 
- * @param tree
- * @param col
- */
 void _gnt_tree_init_internals(GntTree *tree, int col);
 
 #endif /* GNT_TREE_H */