Pileus Git - ~andy/gtk/blob - docs/tree-column-sizing.txt

   1 The way that the GtkTreeView calculates sizing is pretty confusing.
   2 This is written down to help keep track of it in my head, and thus help
   3 anyone who hopes to work with the code in the future.
   4
   5 HOW THE GTKTREEVIEW CALCULATES SIZE:
   6 ====================================
   7 When the view is given a new model, the first thing it does is walk
   8 through the model at the top level, creating an GtkRBNode for each
   9 element of the model.  Each node has a height of 0.  The RBTree is kept
  10 updated as the models structure changes.  Additionally, the user can
  11 expand, collapse, and select rows at this stage.  The RBTree is accurate
  12 -- it just doesn't have a height for any row.
  13
  14 When the TreeView is realized, it calculates the actual height of each
  15 row by walking the tree and measuring them.  While doing so, it gets the
  16 size of each column.
  17
  18
  19
  20 Columns are initially marked as 'dirty'.  When sized,
  21 gtk_tree_view_check_dirty_and_clean () is called on each column.  This
  22 function walks through all visible columns, and sees if they're dirty or
  23 not.  If any are dirty, it then walks the tree, calling
  24 gtk_tree_view_calc_size on each row.  gtk_tree_view_calc_size requests
  25 the size of every dirty column in the tree.  Finally, it updates the
  26 size of the widget (including adjustments).
  27
  28
  29 HOW THE GTKTREEVIEWCOLUMN STORES SIZE:
  30 ======================================
  31
  32 There are a number of size related fields in the GtkTreeViewColumn
  33 structure.  These are all valid after realization:
  34
  35   sizing            The sizing method to use when calculating the size
  36                     of the column.  Can be grow_only, resizable, auto, and fixed.
  37
  38   requested_width   The width of the column as requested by the column
  39
  40   width             The actual width.  This is requested width for all
  41                     columns but possibly the last one.
  42
  43   fixed_width       The requested fixed width for the column iff it's
  44                     sizing type is set to GTK_TREE_VIEW_COLUMN_FIXED.
  45
  46   min_width         The minimum width the column can be
  47
  48   max_width         The maximum width the column can be.  This can be
  49                     overridden for the last column, if the tree_view is
  50                     actually wider than the sum of all of the columns
  51                     requested_widths.
  52
  53 The following invariants are true:
  54
  55 min_width is less than or equal to width
  56
  57 max_width is greater than or equal to width
  58
  59 (sizing == GTK_TREE_VIEW_COLUMN_FIXED) => (requested_width == fixed_width)
  60
  61 (column != last visible column) => width == requested_width
  62
  63
  64 /* Functions needed by gtktreeview for gtktreeviewcolumn */
  65 size_request_button
  66 set_width (for resizing resizable columns)
  67 calculate_width