comparison finch/libgnt/gnttree.h @ 18419:e79da0369a6d

Docs for GntTree.

18418:b51dcbac4798

};

G_BEGIN_DECLS

/**
 * 
 *
 * @return
 */
GType gnt_tree_get_gtype(void);

/**
 * 
 *
 * @return
 */
GntWidget * gnt_tree_new(void);

      /* A tree with just one column */

/**
 * 
 * @param columns
 *
 * @return
 */
GntWidget * gnt_tree_new_with_columns(int columns);

/**
 * 
 * @param tree
 * @param rows
 */
void gnt_tree_set_visible_rows(GntTree *tree, int rows);

/**
 * 
 * @param tree
 *
 * @return
 */
int gnt_tree_get_visible_rows(GntTree *tree);

/**
 * 
 * @param tree
 * @param count
 */
void gnt_tree_scroll(GntTree *tree, int count);

/**
 * 
 * @param tree
 * @param key
 * @param row
 * @param parent
 * @param bigbro
 *
 * @return
 */
GntTreeRow * gnt_tree_add_row_after(GntTree *tree, void *key, GntTreeRow *row, void *parent, void *bigbro);

/**
 * 
 * @param tree
 * @param key
 * @param row
 * @param parent
 *
 * @return
 */
GntTreeRow * gnt_tree_add_row_last(GntTree *tree, void *key, GntTreeRow *row, void *parent);

/**
 * 
 * @param tree
 *
 * @return
 */
gpointer gnt_tree_get_selection_data(GntTree *tree);

/* Returned string needs to be freed */
/**
 * 
 * @param tree
 *
 * @return
 */
char * gnt_tree_get_selection_text(GntTree *tree);

/**
 * 
 * @param tree
 *
 * @return
 */
GList * gnt_tree_get_selection_text_list(GntTree *tree);

/**
 *
 * @param tree
 *
 * @constreturn
 */
GList *gnt_tree_get_rows(GntTree *tree);

/**
 * 
 * @param tree
 * @param key
 */
void gnt_tree_remove(GntTree *tree, gpointer key);

/**
 * 
 * @param tree
 */
void gnt_tree_remove_all(GntTree *tree);

/* Returns the visible line number of the selected row */
/**
 * 
 * @param tree
 *
 * @return
 */
int gnt_tree_get_selection_visible_line(GntTree *tree);

/**
 * 
 * @param tree
 * @param key
 * @param colno
 * @param 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
 *
 * @return
 */
GntTreeRow * gnt_tree_add_choice(GntTree *tree, void *key, GntTreeRow *row, void *parent, void *bigbro);

/**
 * 
 * @param tree
 * @param key
 * @param set
 */
void gnt_tree_set_choice(GntTree *tree, void *key, gboolean set);

/**
 * 
 * @param tree
 * @param key
 *
 * @return
 */
gboolean gnt_tree_get_choice(GntTree *tree, void *key);

/**
 * 
 * @param tree
 * @param key
 * @param flags
 */
void gnt_tree_set_row_flags(GntTree *tree, void *key, GntTextFormatFlags flags);

/**
 * 
 * @param key
 */
void gnt_tree_set_selected(GntTree *tree , void *key);

/**
 * 
 * @param tree
 *
 * @return
 */
GntTreeRow * gnt_tree_create_row(GntTree *tree, ...);

/**
 * 
 * @param tree
 * @param list
 *
 * @return
 */
GntTreeRow * gnt_tree_create_row_from_list(GntTree *tree, GList *list);

/**
 * 
 * @param tree
 * @param col
 * @param width
 */
void gnt_tree_set_col_width(GntTree *tree, int col, int width);

/**
 * Set the title for a column.
 *
 * @param tree   The tree
 * @param index  The index of the column
 * @param title  The title for the column
 */
void gnt_tree_set_column_title(GntTree *tree, int index, const char *title);

/**
 * 
 * @param tree
 */
void gnt_tree_set_column_titles(GntTree *tree, ...);

/**
 * 
 * @param tree
 * @param set
 */
void gnt_tree_set_show_title(GntTree *tree, gboolean set);

/**
 * 
 * @param tree
 * @param func
 */
void gnt_tree_set_compare_func(GntTree *tree, GCompareFunc func);

/**
 * 
 * @param tree
 * @param key
 * @param expanded
 */
void gnt_tree_set_expanded(GntTree *tree, void *key, gboolean expanded);

/**
 * 
 * @param tree
 * @param set
 */
void gnt_tree_set_show_separator(GntTree *tree, gboolean set);

/**
 * 
 * @param tree
 * @param row
 */
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
 */
void gnt_tree_adjust_columns(GntTree *tree);

/**
 * 
 * @param tree
 * @param hash
 * @param eq
 * @param kd
 */
void gnt_tree_set_hash_fns(GntTree *tree, gpointer hash, gpointer eq, gpointer kd);

/**
 * Set whether a column is visible or not.

 * 
 * @param tree  The tree
 * @param col   The index of the column
 * @param res   If @c FALSE, the column will not be resized when the
 *              tree is resized
 */
void gnt_tree_set_column_resizable(GntTree *tree, int col, gboolean res);

/**
 * Set column widths to use when calculating column widths after a tree

 *
 * @param tree   The tree
 * @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.
 */
void gnt_tree_set_column_width_ratio(GntTree *tree, int cols[]);

G_END_DECLS

/* 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 */

18419:e79da0369a6d

};

G_BEGIN_DECLS

/**
 * @return The GType for GntTree
 */
GType gnt_tree_get_gtype(void);

/**
 * Create a tree with one column.
 *
 * @return The newly created tree
 *
 * @see gnt_tree_new_with_columns
 */
GntWidget * gnt_tree_new(void);

/**
 * Create a tree with a specified number of columns.
 *
 * @param columns  Number of columns
 *
 * @return  The newly created tree
 *
 * @see gnt_tree_new
 */
GntWidget * gnt_tree_new_with_columns(int columns);

/**
 * 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);

/**
 * Get the number visible rows.
 *
 * @param tree  The tree
 *
 * @return  The number of visible rows
 */
int gnt_tree_get_visible_rows(GntTree *tree);

/**
 * 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);

/**
 * Insert a row in the tree.
 *
 * @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);

/**
 * Insert a row at the end of the tree.
 *
 * @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);

/**
 * Get the key for the selected row.
 *
 * @param tree  The tree
 *
 * @return   The key for the selected row
 */
gpointer gnt_tree_get_selection_data(GntTree *tree);

/**
 * Get the text displayed for the selected row.
 *
 * @param tree  The tree
 *
 * @return  The text, which needs to be freed by the caller
 */
char * gnt_tree_get_selection_text(GntTree *tree);

/**
 * Get a list of text of the current row.
 *
 * @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  The tree
 *
 * @return 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.
 *
 * @param tree  The tree
 * @param key   The key for the row to remove
 */
void gnt_tree_remove(GntTree *tree, gpointer key);

/**
 * Remove all the item from the tree.
 *
 * @param tree  The tree
 */
void gnt_tree_remove_all(GntTree *tree);

/**
 * Get the visible line number of the selected row.
 *
 * @param tree  The tree
 *
 * @return  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.
 *
 * @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);

/**
 * Add a checkable item in the tree.
 *
 * @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);

/**
 * 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);

/**
 * Return whether a row is selected or not, where the row is a checkable item.
 *
 * @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);

/**
 * 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);

/**
 * 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);

/**
 * Create a row to insert in the tree.
 *
 * @param tree The tree
 * @param ...  A string for each column in the tree
 *
 * @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, ...);

/**
 * Create a row from a list of text.
 *
 * @param tree  The tree
 * @param list  The list containing the text for each column
 *
 * @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);

/**
 * 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);

/**
 * Set the title for a column.
 *
 * @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);

/**
 * 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, ...);

/**
 * 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);

/**
 * 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);

/**
 * 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);

/**
 * 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);

/**
 * 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);

/**
 * Automatically adjust the width of the columns in the tree.
 *
 * @param tree  The tree
 */
void gnt_tree_adjust_columns(GntTree *tree);

/**
 * 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);

/**
 * Set whether a column is visible or not.

 * 
 * @param tree  The tree
 * @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);

/**
 * Set column widths to use when calculating column widths after a tree

 *
 * @param tree   The tree
 * @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[]);

G_END_DECLS

/* The following functions should NOT be used by applications. */

/* This should be called by the subclasses of GntTree's in their _new function */
void _gnt_tree_init_internals(GntTree *tree, int col);

#endif /* GNT_TREE_H */