Pileus Git - ~andy/gtk/blob - gtk/gtkclist.h

   1 /* GTK - The GIMP Toolkit
   2  * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball, Josh MacDonald
   3  * Copyright (C) 1997-1998 Jay Painter <jpaint@serv.net><jpaint@gimp.org>
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Library General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library General Public
  16  * License along with this library; if not, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20 #ifndef __GTK_CLIST_H__
  21 #define __GTK_CLIST_H__
  22
  23 #include <gdk/gdk.h>
  24 #include <gtk/gtksignal.h>
  25 #include <gtk/gtkalignment.h>
  26 #include <gtk/gtklabel.h>
  27 #include <gtk/gtkbutton.h>
  28 #include <gtk/gtkhscrollbar.h>
  29 #include <gtk/gtkvscrollbar.h>
  30
  31 #ifdef __cplusplus
  32 extern "C"
  33 {
  34 #endif                          /* __cplusplus */
  35
  36 /* clist flags */
  37 enum
  38 {
  39   CLIST_FROZEN          = 1 << 0,
  40   CLIST_IN_DRAG         = 1 << 1,
  41   CLIST_ROW_HEIGHT_SET  = 1 << 2,
  42   CLIST_SHOW_TITLES     = 1 << 3
  43 };
  44
  45 /* cell types */
  46 typedef enum
  47 {
  48   GTK_CELL_EMPTY,
  49   GTK_CELL_TEXT,
  50   GTK_CELL_PIXMAP,
  51   GTK_CELL_PIXTEXT,
  52   GTK_CELL_WIDGET
  53 } GtkCellType;
  54
  55 #define GTK_CLIST(obj)          GTK_CHECK_CAST (obj, gtk_clist_get_type (), GtkCList)
  56 #define GTK_CLIST_CLASS(klass)  GTK_CHECK_CLASS_CAST (klass, gtk_clist_get_type (), GtkCListClass)
  57 #define GTK_IS_CLIST(obj)       GTK_CHECK_TYPE (obj, gtk_clist_get_type ())
  58
  59 #define GTK_CLIST_FLAGS(clist)             (GTK_CLIST (clist)->flags)
  60 #define GTK_CLIST_SET_FLAGS(clist,flag)    (GTK_CLIST_FLAGS (clist) |= (flag))
  61 #define GTK_CLIST_UNSET_FLAGS(clist,flag)  (GTK_CLIST_FLAGS (clist) &= ~(flag))
  62
  63 #define GTK_CLIST_FROZEN(clist)            (GTK_CLIST_FLAGS (clist) & CLIST_FROZEN)
  64 #define GTK_CLIST_IN_DRAG(clist)           (GTK_CLIST_FLAGS (clist) & CLIST_IN_DRAG)
  65 #define GTK_CLIST_ROW_HEIGHT_SET(clist)    (GTK_CLIST_FLAGS (clist) & CLIST_ROW_HEIGHT_SET)
  66 #define GTK_CLIST_SHOW_TITLES(clist)       (GTK_CLIST_FLAGS (clist) & CLIST_SHOW_TITLES)
  67
  68 /* pointer casting for cells */
  69 #define GTK_CELL_TEXT(cell)     (((GtkCellText *) &(cell)))
  70 #define GTK_CELL_PIXMAP(cell)   (((GtkCellPixmap *) &(cell)))
  71 #define GTK_CELL_PIXTEXT(cell)  (((GtkCellPixText *) &(cell)))
  72 #define GTK_CELL_WIDGET(cell)   (((GtkCellWidget *) &(cell)))
  73
  74 typedef struct _GtkCList GtkCList;
  75 typedef struct _GtkCListClass GtkCListClass;
  76 typedef struct _GtkCListColumn GtkCListColumn;
  77 typedef struct _GtkCListRow GtkCListRow;
  78
  79 typedef struct _GtkCell GtkCell;
  80 typedef struct _GtkCellText GtkCellText;
  81 typedef struct _GtkCellPixmap GtkCellPixmap;
  82 typedef struct _GtkCellPixText GtkCellPixText;
  83 typedef struct _GtkCellWidget GtkCellWidget;
  84
  85 struct _GtkCList
  86 {
  87   GtkContainer container;
  88
  89   guint8 flags;
  90
  91   /* mem chunks */
  92   GMemChunk *row_mem_chunk;
  93   GMemChunk *cell_mem_chunk;
  94
  95   /* allocation rectangle after the conatiner_border_width
  96    * and the width of the shadow border */
  97   GdkRectangle internal_allocation;
  98
  99   /* rows */
 100   gint rows;
 101   gint row_center_offset;
 102   gint row_height;
 103   GList *row_list;
 104   GList *row_list_end;
 105
 106   /* columns */
 107   gint columns;
 108   GdkRectangle column_title_area;
 109   GdkWindow *title_window;
 110
 111   /* dynamicly allocated array of column structures */
 112   GtkCListColumn *column;
 113
 114   /*the scrolling window and it's height and width to
 115    * make things a little speedier */
 116   GdkWindow *clist_window;
 117   gint clist_window_width;
 118   gint clist_window_height;
 119
 120   /* offsets for scrolling */
 121   gint hoffset;
 122   gint voffset;
 123
 124   /* border shadow style */
 125   GtkShadowType shadow_type;
 126
 127   /* the list's selection mode (gtkenums.h) */
 128   GtkSelectionMode selection_mode;
 129
 130   /* list of selected rows */
 131   GList *selection;
 132
 133   /* scrollbars */
 134   GtkWidget *vscrollbar;
 135   GtkWidget *hscrollbar;
 136   guint8 vscrollbar_policy;
 137   guint8 hscrollbar_policy;
 138
 139   /* xor GC for the vertical drag line */
 140   GdkGC *xor_gc;
 141
 142   /* gc for drawing unselected cells */
 143   GdkGC *fg_gc;
 144   GdkGC *bg_gc;
 145
 146   /* cursor used to indicate dragging */
 147   GdkCursor *cursor_drag;
 148
 149   /* the current x-pixel location of the xor-drag line */
 150   gint x_drag;
 151 };
 152
 153 struct _GtkCListClass
 154 {
 155   GtkContainerClass parent_class;
 156
 157   void (*select_row) (GtkCList * clist,
 158                       gint row,
 159                       gint column,
 160                       GdkEventButton * event);
 161   void (*unselect_row) (GtkCList * clist,
 162                         gint row,
 163                         gint column,
 164                         GdkEventButton * event);
 165   void (*click_column) (GtkCList * clist,
 166                         gint column);
 167
 168   gint scrollbar_spacing;
 169 };
 170
 171 struct _GtkCListColumn
 172 {
 173   gchar *title;
 174   GdkRectangle area;
 175
 176   GtkWidget *button;
 177   GdkWindow *window;
 178
 179   gint width;
 180   GtkJustification justification;
 181
 182   gint width_set : 1;
 183 };
 184
 185 struct _GtkCListRow
 186 {
 187   GtkCell *cell;
 188   GtkStateType state;
 189
 190   GdkColor foreground;
 191   GdkColor background;
 192
 193   gpointer data;
 194   GtkDestroyNotify destroy;
 195
 196   gint fg_set : 1;
 197   gint bg_set : 1;
 198 };
 199
 200 /* Cell Structures */
 201 struct _GtkCellText
 202 {
 203   GtkCellType type;
 204
 205   gint vertical;
 206   gint horizontal;
 207
 208   gchar *text;
 209 };
 210
 211 struct _GtkCellPixmap
 212 {
 213   GtkCellType type;
 214
 215   gint vertical;
 216   gint horizontal;
 217
 218   GdkPixmap *pixmap;
 219   GdkBitmap *mask;
 220 };
 221
 222 struct _GtkCellPixText
 223 {
 224   GtkCellType type;
 225
 226   gint vertical;
 227   gint horizontal;
 228
 229   gchar *text;
 230   guint8 spacing;
 231   GdkPixmap *pixmap;
 232   GdkBitmap *mask;
 233 };
 234
 235 struct _GtkCellWidget
 236 {
 237   GtkCellType type;
 238
 239   gint vertical;
 240   gint horizontal;
 241
 242   GtkWidget *widget;
 243 };
 244
 245 struct _GtkCell
 246 {
 247   GtkCellType type;
 248
 249   gint vertical;
 250   gint horizontal;
 251
 252   union {
 253     gchar *text;
 254
 255     struct {
 256       GdkPixmap *pixmap;
 257       GdkBitmap *mask;
 258     } pm;
 259
 260     struct {
 261       gchar *text;
 262       guint8 spacing;
 263       GdkPixmap *pixmap;
 264       GdkBitmap *mask;
 265     } pt;
 266
 267     GtkWidget *widget;
 268   } u;
 269 };
 270
 271 guint gtk_clist_get_type (void);
 272
 273 /* constructers useful for gtk-- wrappers */
 274 void gtk_clist_construct (GtkCList * clist,
 275                           gint columns,
 276                           gchar * titles[]);
 277
 278 /* create a new GtkCList */
 279 GtkWidget *gtk_clist_new (gint columns);
 280 GtkWidget *gtk_clist_new_with_titles (gint columns,
 281                                       gchar * titles[]);
 282
 283 /* set the border style of the clist */
 284 void gtk_clist_set_border (GtkCList * clist,
 285                            GtkShadowType border);
 286
 287 /* set the clist's selection mode */
 288 void gtk_clist_set_selection_mode (GtkCList * clist,
 289                                    GtkSelectionMode mode);
 290
 291 /* set policy on the scrollbar, to either show them all the time
 292  * or show them only when they are needed, ie., when there is more than one page
 293  * of information */
 294 void gtk_clist_set_policy (GtkCList * clist,
 295                            GtkPolicyType vscrollbar_policy,
 296                            GtkPolicyType hscrollbar_policy);
 297
 298 /* freeze all visual updates of the list, and then thaw the list after you have made
 299  * a number of changes and the updates wil occure in a more efficent mannor than if
 300  * you made them on a unfrozen list */
 301 void gtk_clist_freeze (GtkCList * clist);
 302 void gtk_clist_thaw (GtkCList * clist);
 303
 304 /* show and hide the column title buttons */
 305 void gtk_clist_column_titles_show (GtkCList * clist);
 306 void gtk_clist_column_titles_hide (GtkCList * clist);
 307
 308 /* set the column title to be a active title (responds to button presses,
 309  * prelights, and grabs keyboard focus), or passive where it acts as just
 310  * a title */
 311 void gtk_clist_column_title_active (GtkCList * clist,
 312                                      gint column);
 313 void gtk_clist_column_title_passive (GtkCList * clist,
 314                                      gint column);
 315 void gtk_clist_column_titles_active (GtkCList * clist);
 316 void gtk_clist_column_titles_passive (GtkCList * clist);
 317
 318 /* set the title in the column title button */
 319 void gtk_clist_set_column_title (GtkCList * clist,
 320                                  gint column,
 321                                  gchar * title);
 322
 323 /* set a widget instead of a title for the column title button */
 324 void gtk_clist_set_column_widget (GtkCList * clist,
 325                                   gint column,
 326                                   GtkWidget * widget);
 327
 328 /* set the justification on a column */
 329 void gtk_clist_set_column_justification (GtkCList * clist,
 330                                          gint column,
 331                                          GtkJustification justification);
 332
 333 /* set the pixel width of a column; this is a necessary step in
 334  * creating a CList because otherwise the column width is chozen from
 335  * the width of the column title, which will never be right */
 336 void gtk_clist_set_column_width (GtkCList * clist,
 337                                  gint column,
 338                                  gint width);
 339
 340 /* change the height of the rows, the default is the hight of the current
 341  * font */
 342 void gtk_clist_set_row_height (GtkCList * clist,
 343                                gint height);
 344
 345 /* scroll the viewing area of the list to the given column
 346  * and row; row_align and col_align are between 0-1 representing the
 347  * location the row should appear on the screnn, 0.0 being top or left,
 348  * 1.0 being bottom or right; if row or column is -1 then then there
 349  * is no change */
 350 void gtk_clist_moveto (GtkCList * clist,
 351                        gint row,
 352                        gint column,
 353                        gfloat row_align,
 354                        gfloat col_align);
 355
 356 /* returns whether the row is visible */
 357 GtkVisibility gtk_clist_row_is_visible (GtkCList * clist,
 358                                         gint row);
 359
 360 /* returns the cell type */
 361 GtkCellType gtk_clist_get_cell_type (GtkCList * clist,
 362                                      gint row,
 363                                      gint column);
 364
 365 /* sets a given cell's text, replacing it's current contents */
 366 void gtk_clist_set_text (GtkCList * clist,
 367                          gint row,
 368                          gint column,
 369                          gchar * text);
 370
 371 /* for the "get" functions, any of the return pointer can be
 372  * NULL if you are not interested */
 373 gint gtk_clist_get_text (GtkCList * clist,
 374                          gint row,
 375                          gint column,
 376                          gchar ** text);
 377
 378 /* sets a given cell's pixmap, replacing it's current contents */
 379 void gtk_clist_set_pixmap (GtkCList * clist,
 380                            gint row,
 381                            gint column,
 382                            GdkPixmap * pixmap,
 383                            GdkBitmap * mask);
 384
 385 gint gtk_clist_get_pixmap (GtkCList * clist,
 386                            gint row,
 387                            gint column,
 388                            GdkPixmap ** pixmap,
 389                            GdkBitmap ** mask);
 390
 391 /* sets a given cell's pixmap and text, replacing it's current contents */
 392 void gtk_clist_set_pixtext (GtkCList * clist,
 393                             gint row,
 394                             gint column,
 395                             gchar * text,
 396                             guint8 spacing,
 397                             GdkPixmap * pixmap,
 398                             GdkBitmap * mask);
 399
 400 gint gtk_clist_get_pixtext (GtkCList * clist,
 401                             gint row,
 402                             gint column,
 403                             gchar ** text,
 404                             guint8 * spacing,
 405                             GdkPixmap ** pixmap,
 406                             GdkBitmap ** mask);
 407
 408 /* sets the foreground color of a row, the colar must already
 409  * be allocated */
 410 void gtk_clist_set_foreground (GtkCList * clist,
 411                                gint row,
 412                                GdkColor * color);
 413
 414 /* sets the background color of a row, the colar must already
 415  * be allocated */
 416 void gtk_clist_set_background (GtkCList * clist,
 417                                gint row,
 418                                GdkColor * color);
 419
 420 /* this sets a horizontal and vertical shift for drawing
 421  * the contents of a cell; it can be positive or negitive; this is
 422  * partuculary useful for indenting items in a column */
 423 void gtk_clist_set_shift (GtkCList * clist,
 424                           gint row,
 425                           gint column,
 426                           gint vertical,
 427                           gint horizontal);
 428
 429 /* append returns the index of the row you just added, making
 430  * it easier to append and modify a row */
 431 gint gtk_clist_append (GtkCList * clist,
 432                        gchar * text[]);
 433
 434 /* inserts a row at index row */
 435 void gtk_clist_insert (GtkCList * clist,
 436                        gint row,
 437                        gchar * text[]);
 438
 439 /* removes row at index row */
 440 void gtk_clist_remove (GtkCList * clist,
 441                        gint row);
 442
 443 /* sets a arbitrary data pointer for a given row */
 444 void gtk_clist_set_row_data (GtkCList * clist,
 445                              gint row,
 446                              gpointer data);
 447
 448 /* sets a data pointer for a given row with destroy notification */
 449 void gtk_clist_set_row_data_full (GtkCList * clist,
 450                                   gint row,
 451                                   gpointer data,
 452                                   GtkDestroyNotify destroy);
 453
 454 /* returns the data set for a row */
 455 gpointer gtk_clist_get_row_data (GtkCList * clist,
 456                                  gint row);
 457
 458 /* givin a data pointer, find the first (and hopefully only!)
 459  * row that points to that data, or -1 if none do */
 460 gint gtk_clist_find_row_from_data (GtkCList * clist,
 461                                    gpointer data);
 462
 463 /* force selection of a row */
 464 void gtk_clist_select_row (GtkCList * clist,
 465                            gint row,
 466                            gint column);
 467
 468 /* force unselection of a row */
 469 void gtk_clist_unselect_row (GtkCList * clist,
 470                              gint row,
 471                              gint column);
 472
 473 /* clear the entire list -- this is much faster than removing each item
 474  * with gtk_clist_remove */
 475 void gtk_clist_clear (GtkCList * clist);
 476
 477 /* return the row column corresponding to the x and y coordinates */
 478 gint gtk_clist_get_selection_info (GtkCList * clist,
 479                                    gint x,
 480                                    gint y,
 481                                    gint * row,
 482                                    gint * column);
 483
 484 #ifdef __cplusplus
 485 }
 486 #endif                          /* __cplusplus */
 487
 488
 489 #endif                          /* __GTK_CLIST_H__ */