finch/libgnt/gnttree.h

   1 /**
   2  * @file gnttree.h Tree API
   3  * @ingroup gnt
   4  */
   5 /*
   6  * GNT - The GLib Ncurses Toolkit
   7  *
   8  * GNT is the legal property of its developers, whose names are too numerous
   9  * to list here.  Please refer to the COPYRIGHT file distributed with this
  10  * source distribution.
  11  *
  12  * This library is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with this program; if not, write to the Free Software
  24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02111-1301  USA
  25  */
  26
  27 #ifndef GNT_TREE_H
  28 #define GNT_TREE_H
  29
  30 #include "gntwidget.h"
  31 #include "gnt.h"
  32 #include "gntcolors.h"
  33 #include "gntkeys.h"
  34 #include "gnttextview.h"
  35
  36 #define GNT_TYPE_TREE                           (gnt_tree_get_gtype())
  37 #define GNT_TREE(obj)                           (G_TYPE_CHECK_INSTANCE_CAST((obj), GNT_TYPE_TREE, GntTree))
  38 #define GNT_TREE_CLASS(klass)           (G_TYPE_CHECK_CLASS_CAST((klass), GNT_TYPE_TREE, GntTreeClass))
  39 #define GNT_IS_TREE(obj)                        (G_TYPE_CHECK_INSTANCE_TYPE((obj), GNT_TYPE_TREE))
  40 #define GNT_IS_TREE_CLASS(klass)        (G_TYPE_CHECK_CLASS_TYPE((klass), GNT_TYPE_TREE))
  41 #define GNT_TREE_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), GNT_TYPE_TREE, GntTreeClass))
  42
  43 typedef struct _GntTree                 GntTree;
  44 typedef struct _GntTreePriv             GntTreePriv;
  45 typedef struct _GntTreeClass            GntTreeClass;
  46
  47 typedef struct _GntTreeRow              GntTreeRow;
  48 typedef struct _GntTreeCol              GntTreeCol;
  49
  50 typedef enum _GntTreeColumnFlag {
  51         GNT_TREE_COLUMN_INVISIBLE    = 1 << 0,
  52         GNT_TREE_COLUMN_FIXED_SIZE   = 1 << 1,
  53         GNT_TREE_COLUMN_BINARY_DATA  = 1 << 2,
  54         GNT_TREE_COLUMN_RIGHT_ALIGNED = 1 << 3,
  55 } GntTreeColumnFlag;
  56
  57 struct _GntTree
  58 {
  59         GntWidget parent;
  60
  61         GntTreeRow *current;    /* current selection */
  62
  63         GntTreeRow *top;        /* The topmost visible item */
  64         GntTreeRow *bottom;     /* The bottommost visible item */
  65
  66         GntTreeRow *root;       /* The root of all evil */
  67
  68         GList *list;            /* List of GntTreeRow s */
  69         GHashTable *hash;       /* We need this for quickly referencing the rows */
  70         guint (*hash_func)(gconstpointer);
  71         gboolean (*hash_eq_func)(gconstpointer, gconstpointer);
  72         GDestroyNotify key_destroy;
  73         GDestroyNotify value_destroy;
  74
  75         int ncol;               /* No. of columns */
  76         struct _GntTreeColInfo
  77         {
  78                 int width;
  79                 char *title;
  80                 int width_ratio;
  81                 GntTreeColumnFlag flags;
  82         } *columns;             /* Would a GList be better? */
  83         gboolean show_title;
  84         gboolean show_separator; /* Whether to show column separators */
  85
  86         GntTreePriv *priv;
  87 };
  88
  89 struct _GntTreeClass
  90 {
  91         GntWidgetClass parent;
  92
  93         void (*selection_changed)(GntTreeRow *old, GntTreeRow * current);
  94         void (*toggled)(GntTree *tree, gpointer key);
  95
  96         void (*gnt_reserved1)(void);
  97         void (*gnt_reserved2)(void);
  98         void (*gnt_reserved3)(void);
  99         void (*gnt_reserved4)(void);
 100 };
 101
 102 G_BEGIN_DECLS
 103
 104 /**
 105  * @return The GType for GntTree
 106  */
 107 GType gnt_tree_get_gtype(void);
 108
 109 /**
 110  * Create a tree with one column.
 111  *
 112  * @return The newly created tree
 113  *
 114  * @see gnt_tree_new_with_columns
 115  */
 116 GntWidget * gnt_tree_new(void);
 117
 118 /**
 119  * Create a tree with a specified number of columns.
 120  *
 121  * @param columns  Number of columns
 122  *
 123  * @return  The newly created tree
 124  *
 125  * @see gnt_tree_new
 126  */
 127 GntWidget * gnt_tree_new_with_columns(int columns);
 128
 129 /**
 130  * The number of rows the tree should display at a time.
 131  *
 132  * @param tree  The tree
 133  * @param rows  The number of rows
 134  */
 135 void gnt_tree_set_visible_rows(GntTree *tree, int rows);
 136
 137 /**
 138  * Get the number visible rows.
 139  *
 140  * @param tree  The tree
 141  *
 142  * @return  The number of visible rows
 143  */
 144 int gnt_tree_get_visible_rows(GntTree *tree);
 145
 146 /**
 147  * Scroll the contents of the tree.
 148  *
 149  * @param tree   The tree
 150  * @param count  If positive, the tree will be scrolled down by count rows,
 151  *               otherwise, it will be scrolled up by count rows.
 152  */
 153 void gnt_tree_scroll(GntTree *tree, int count);
 154
 155 /**
 156  * Insert a row in the tree.
 157  *
 158  * @param tree    The tree
 159  * @param key     The key for the row
 160  * @param row     The row to insert
 161  * @param parent  The key for the parent row
 162  * @param bigbro  The key for the row to insert the new row after.
 163  *
 164  * @return  The inserted row
 165  *
 166  * @see gnt_tree_create_row
 167  * @see gnt_tree_add_row_last
 168  * @see gnt_tree_add_choice
 169  */
 170 GntTreeRow * gnt_tree_add_row_after(GntTree *tree, void *key, GntTreeRow *row, void *parent, void *bigbro);
 171
 172 /**
 173  * Insert a row at the end of the tree.
 174  *
 175  * @param tree    The tree
 176  * @param key     The key for the row
 177  * @param row     The row to insert
 178  * @param parent  The key for the parent row
 179  *
 180  * @return The inserted row
 181  *
 182  * @see gnt_tree_create_row
 183  * @see gnt_tree_add_row_after
 184  * @see gnt_tree_add_choice
 185  */
 186 GntTreeRow * gnt_tree_add_row_last(GntTree *tree, void *key, GntTreeRow *row, void *parent);
 187
 188 /**
 189  * Get the key for the selected row.
 190  *
 191  * @param tree  The tree
 192  *
 193  * @return   The key for the selected row
 194  */
 195 gpointer gnt_tree_get_selection_data(GntTree *tree);
 196
 197 /**
 198  * Get the text displayed for the selected row.
 199  *
 200  * @param tree  The tree
 201  *
 202  * @return  The text, which needs to be freed by the caller
 203  * @see gnt_tree_get_row_text_list
 204  * @see gnt_tree_get_selection_text_list
 205  */
 206 char * gnt_tree_get_selection_text(GntTree *tree);
 207
 208 /**
 209  * Get a list of text for a row.
 210  *
 211  * @param tree  The tree
 212  * @param key   A key corresponding to the row in question. If key
 213  *              is @c NULL, the text list for the selected row will
 214  *              be returned.
 215  *
 216  * @return A list of texts of a row. The list and its data should be
 217  *         freed by the caller. The caller should make sure that if
 218  *         any column of the tree contains binary data, it's not freed.
 219  * @see gnt_tree_get_selection_text_list
 220  * @see gnt_tree_get_selection_text
 221  */
 222 GList * gnt_tree_get_row_text_list(GntTree *tree, gpointer key);
 223
 224 /**
 225  * Get a list of text of the current row.
 226  *
 227  * @param tree  The tree
 228  *
 229  * @return A list of texts of the currently selected row. The list
 230  *         and its data should be freed by the caller. The caller
 231  *         should make sure that if any column of the tree contains
 232  *         binary data, it's not freed.
 233  * @see gnt_tree_get_row_text_list
 234  * @see gnt_tree_get_selection_text
 235  */
 236 GList * gnt_tree_get_selection_text_list(GntTree *tree);
 237
 238 /**
 239  * Returns the list of rows in the tree.
 240  *
 241  * @param tree  The tree
 242  *
 243  * @return The list of the rows. The list should not be modified by the caller.
 244  */
 245 GList *gnt_tree_get_rows(GntTree *tree);
 246
 247 /**
 248  * Remove a row from the tree.
 249  *
 250  * @param tree  The tree
 251  * @param key   The key for the row to remove
 252  */
 253 void gnt_tree_remove(GntTree *tree, gpointer key);
 254
 255 /**
 256  * Remove all the item from the tree.
 257  *
 258  * @param tree  The tree
 259  */
 260 void gnt_tree_remove_all(GntTree *tree);
 261
 262 /**
 263  * Get the visible line number of the selected row.
 264  *
 265  * @param tree  The tree
 266  *
 267  * @return  The line number of the currently selected row
 268  */
 269 int gnt_tree_get_selection_visible_line(GntTree *tree);
 270
 271 /**
 272  * Change the text of a column in a row.
 273  *
 274  * @param tree   The tree
 275  * @param key    The key for the row
 276  * @param colno  The index of the column
 277  * @param text   The new text
 278  */
 279 void gnt_tree_change_text(GntTree *tree, gpointer key, int colno, const char *text);
 280
 281 /**
 282  * Add a checkable item in the tree.
 283  *
 284  * @param tree    The tree
 285  * @param key     The key for the row
 286  * @param row     The row to add
 287  * @param parent  The parent of the row, or @c NULL
 288  * @param bigbro  The row to insert after, or @c NULL
 289  *
 290  * @return  The row inserted.
 291  *
 292  * @see gnt_tree_create_row
 293  * @see gnt_tree_create_row_from_list
 294  * @see gnt_tree_add_row_last
 295  * @see gnt_tree_add_row_after
 296  */
 297 GntTreeRow * gnt_tree_add_choice(GntTree *tree, void *key, GntTreeRow *row, void *parent, void *bigbro);
 298
 299 /**
 300  * Set whether a checkable item is checked or not.
 301  *
 302  * @param tree   The tree
 303  * @param key    The key for the row
 304  * @param set    @c TRUE if the item should be checked, @c FALSE if not
 305  */
 306 void gnt_tree_set_choice(GntTree *tree, void *key, gboolean set);
 307
 308 /**
 309  * Return whether a row is selected or not, where the row is a checkable item.
 310  *
 311  * @param tree  The tree
 312  * @param key   The key for the row
 313  *
 314  * @return    @c TRUE if the row is checked, @c FALSE otherwise.
 315  */
 316 gboolean gnt_tree_get_choice(GntTree *tree, void *key);
 317
 318 /**
 319  * Set flags for the text in a row in the tree.
 320  *
 321  * @param tree   The tree
 322  * @param key    The key for the row
 323  * @param flags  The flags to set
 324  */
 325 void gnt_tree_set_row_flags(GntTree *tree, void *key, GntTextFormatFlags flags);
 326
 327 /**
 328  * Set color for the text in a row in the tree.
 329  *
 330  * @param tree   The tree
 331  * @param key    The key for the row
 332  * @param color  The color
 333  * @since 2.4.0
 334  */
 335 void gnt_tree_set_row_color(GntTree *tree, void *key, int color);
 336
 337 /**
 338  * Select a row.
 339  *
 340  * @param tree  The tree
 341  * @param key   The key of the row to select
 342  */
 343 void gnt_tree_set_selected(GntTree *tree , void *key);
 344
 345 /**
 346  * Create a row to insert in the tree.
 347  *
 348  * @param tree The tree
 349  * @param ...  A string for each column in the tree
 350  *
 351  * @return   The row
 352  *
 353  * @see gnt_tree_create_row_from_list
 354  * @see gnt_tree_add_row_after
 355  * @see gnt_tree_add_row_last
 356  * @see gnt_tree_add_choice
 357  */
 358 GntTreeRow * gnt_tree_create_row(GntTree *tree, ...);
 359
 360 /**
 361  * Create a row from a list of text.
 362  *
 363  * @param tree  The tree
 364  * @param list  The list containing the text for each column
 365  *
 366  * @return   The row
 367  *
 368  * @see gnt_tree_create_row
 369  * @see gnt_tree_add_row_after
 370  * @see gnt_tree_add_row_last
 371  * @see gnt_tree_add_choice
 372  */
 373 GntTreeRow * gnt_tree_create_row_from_list(GntTree *tree, GList *list);
 374
 375 /**
 376  * Set the width of a column in the tree.
 377  *
 378  * @param tree   The tree
 379  * @param col    The index of the column
 380  * @param width  The width for the column
 381  *
 382  * @see gnt_tree_set_column_width_ratio
 383  * @see gnt_tree_set_column_resizable
 384  */
 385 void gnt_tree_set_col_width(GntTree *tree, int col, int width);
 386
 387 /**
 388  * Set the title for a column.
 389  *
 390  * @param tree   The tree
 391  * @param index  The index of the column
 392  * @param title  The title for the column
 393  *
 394  * @see gnt_tree_set_column_titles
 395  * @see gnt_tree_set_show_title
 396  *
 397  * @since 2.0.0 (gnt), 2.1.0 (pidgin)
 398  */
 399 void gnt_tree_set_column_title(GntTree *tree, int index, const char *title);
 400
 401 /**
 402  * Set the titles of the columns
 403  *
 404  * @param tree  The tree
 405  * @param ...   One title for each column in the tree
 406  *
 407  * @see gnt_tree_set_column_title
 408  * @see gnt_tree_set_show_title
 409  */
 410 void gnt_tree_set_column_titles(GntTree *tree, ...);
 411
 412 /**
 413  * Set whether to display the title of the columns.
 414  *
 415  * @param tree  The tree
 416  * @param set   If @c TRUE, the column titles are displayed
 417  *
 418  * @see gnt_tree_set_column_title
 419  * @see gnt_tree_set_column_titles
 420  */
 421 void gnt_tree_set_show_title(GntTree *tree, gboolean set);
 422
 423 /**
 424  * Set the compare function for sorting the data.
 425  *
 426  * @param tree  The tree
 427  * @param func  The comparison function, which is used to compare
 428  *              the keys
 429  *
 430  * @see gnt_tree_sort_row
 431  */
 432 void gnt_tree_set_compare_func(GntTree *tree, GCompareFunc func);
 433
 434 /**
 435  * Set whether a row, which has child rows, should be expanded.
 436  *
 437  * @param tree      The tree
 438  * @param key       The key of the row
 439  * @param expanded  Whether to expand the child rows
 440  */
 441 void gnt_tree_set_expanded(GntTree *tree, void *key, gboolean expanded);
 442
 443 /**
 444  * Set whether to show column separators.
 445  *
 446  * @param tree  The tree
 447  * @param set   If @c TRUE, the column separators are displayed
 448  */
 449 void gnt_tree_set_show_separator(GntTree *tree, gboolean set);
 450
 451 /**
 452  * Sort a row in the tree.
 453  *
 454  * @param tree  The tree
 455  * @param row   The row to sort
 456  *
 457  * @see gnt_tree_set_compare_func
 458  */
 459 void gnt_tree_sort_row(GntTree *tree, void *row);
 460
 461 /**
 462  * Automatically adjust the width of the columns in the tree.
 463  *
 464  * @param tree  The tree
 465  */
 466 void gnt_tree_adjust_columns(GntTree *tree);
 467
 468 /**
 469  * Set the hash functions to use to hash, compare and free the keys.
 470  *
 471  * @param tree  The tree
 472  * @param hash  The hashing function
 473  * @param eq    The function to compare keys
 474  * @param kd    The function to use to free the keys when a row is removed
 475  *              from the tree
 476  */
 477 void gnt_tree_set_hash_fns(GntTree *tree, gpointer hash, gpointer eq, gpointer kd);
 478
 479 /**
 480  * Set whether a column is visible or not.
 481  * This can be useful when, for example, we want to store some data
 482  * which we don't want/need to display.
 483  *
 484  * @param tree  The tree
 485  * @param col   The index of the column
 486  * @param vis   If @c FALSE, the column will not be displayed
 487  */
 488 void gnt_tree_set_column_visible(GntTree *tree, int col, gboolean vis);
 489
 490 /**
 491  * Set whether a column can be resized to keep the same ratio when the
 492  * tree is resized.
 493  *
 494  * @param tree  The tree
 495  * @param col   The index of the column
 496  * @param res   If @c FALSE, the column will not be resized when the
 497  *              tree is resized
 498  *
 499  * @see gnt_tree_set_col_width
 500  * @see gnt_tree_set_column_width_ratio
 501  *
 502  * @since 2.0.0 (gnt), 2.1.0 (pidgin)
 503  */
 504 void gnt_tree_set_column_resizable(GntTree *tree, int col, gboolean res);
 505
 506 /**
 507  * Set whether data in a column should be considered as binary data, and
 508  * not as strings. A column containing binary data will be display empty text.
 509  *
 510  * @param tree  The tree
 511  * @param col   The index of the column
 512  * @param bin   @c TRUE if the data for the column is binary
 513  */
 514 void gnt_tree_set_column_is_binary(GntTree *tree, int col, gboolean bin);
 515
 516 /**
 517  * Set whether text in a column should be right-aligned.
 518  *
 519  * @param tree  The tree
 520  * @param col   The index of the column
 521  * @param right @c TRUE if the text in the column should be right aligned
 522  *
 523  * @since 2.0.0 (gnt), 2.1.0 (pidgin)
 524  */
 525 void gnt_tree_set_column_is_right_aligned(GntTree *tree, int col, gboolean right);
 526
 527 /**
 528  * Set column widths to use when calculating column widths after a tree
 529  * is resized.
 530  *
 531  * @param tree   The tree
 532  * @param cols   Array of widths. The width must have the same number
 533  *               of entries as the number of columns in the tree, or
 534  *               end with a negative value for a column-width.
 535  *
 536  * @see gnt_tree_set_col_width
 537  * @see gnt_tree_set_column_resizable
 538  *
 539  * @since 2.0.0 (gnt), 2.1.0 (pidgin)
 540  */
 541 void gnt_tree_set_column_width_ratio(GntTree *tree, int cols[]);
 542
 543 /**
 544  * Set the column to use for typeahead searching.
 545  *
 546  * @param tree   The tree
 547  * @param col    The index of the column
 548  *
 549  * @since 2.0.0 (gnt), 2.1.0 (pidgin)
 550  */
 551 void gnt_tree_set_search_column(GntTree *tree, int col);
 552
 553 /**
 554  * Check whether the user is currently in the middle of a search.
 555  *
 556  * @param tree   The tree
 557  * @return  @c TRUE if the user is searching, @c FALSE otherwise.
 558  *
 559  * @since 2.0.0 (gnt), 2.1.0 (pidgin)
 560  */
 561 gboolean gnt_tree_is_searching(GntTree *tree);
 562
 563 /**
 564  * Set a custom search function.
 565  *
 566  * @param tree  The tree
 567  * @param func  The custom search function. The search function is
 568  *              sent the tree itself, the key of a row, the search
 569  *              string and the content of row in the search column.
 570  *              If the function returns @c TRUE, the row is dislayed,
 571  *              otherwise it's not.
 572  *
 573  * @since 2.0.0 (gnt), 2.1.0 (pidgin)
 574  */
 575 void gnt_tree_set_search_function(GntTree *tree,
 576                 gboolean (*func)(GntTree *tree, gpointer key, const char *search, const char *current));
 577
 578 /**
 579  * Get the parent key for a row.
 580  *
 581  * @param  tree  The tree
 582  * @param  key   The key for the row.
 583  *
 584  * @return The key of the parent row.
 585  * @since 2.4.0
 586  */
 587 gpointer gnt_tree_get_parent_key(GntTree *tree, gpointer key);
 588
 589 G_END_DECLS
 590
 591 #endif /* GNT_TREE_H */