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.
6 HOW THE GTKTREEVIEW CALCULATES SIZE:
7 ====================================
8 When the view is given a new model, the first thing it does is walk
9 through the model at the top level, creating an GtkRBNode for each
10 element of the model. Each node has a height of 0. The RBTree is kept
11 updated as the models structure changes. Additionally, the user can
12 expand, collapse, and select rows at this stage. The RBTree is accurate
13 -- it just has a height of zero for every row.
15 When the widget is realized, it calls install_presize_handler, to setup
16 the first-run function. This is run before the expose event.
18 HOW THE GTKTREEVIEWCOLUMN STORES SIZE:
19 ======================================
21 There are a number of size related fields in the GtkTreeViewColumn
22 structure. These are all valid after realization:
24 column_type The sizing method to use when calculating the size
25 of the column. Can be GROW_ONLY, AUTO, and FIXED.
27 button_request The width as requested by the button.
29 requested_width The width of the column as requested by the column.
30 It is the max requested width of the bcells in the
31 column. If the column_type is AUTO, then it is
32 recalculated when a column changes. Otherwise, it
35 resized_width The width after the user has resized the column.
37 width The actual width of the column as displayed.
39 fixed_width The requested fixed width for the column iff it's
40 sizing type is set to GTK_TREE_VIEW_COLUMN_FIXED.
41 Used instead of requested_width in that case.
43 min_width The minimum width the column can be. If set to -1,
44 this field is considered unset.
46 max_width The maximum width the column can be. This can be
47 overridden for the last column, if the tree_view is
48 actually wider than the sum of all of the columns
49 requested_widths. If set to -1, this field is
53 use_resized_width Use resized_width to determine the size.
57 tree_view->priv->width = the width the widget wants to be, including headers.
58 tree_view->priv->height = the height the widget requests. It's the sum
59 of the width of all visible columns.
61 Both of these are calculated in _gtk_tree_view_update_size
65 The following invariants are true:
67 min_width is less than or equal to width
69 max_width is greater than or equal to width
71 min_width <= max_width
73 (sizing == GTK_TREE_VIEW_COLUMN_FIXED) => (requested_width == fixed_width)
75 (column != last visible column) => width == CLAMP (requested_width, min_width, max_width)
78 HOW THE VERTICAL OFFSET IS CALCULATED
79 (This has nothing to do with columns)
80 =====================================
82 The current offset of the tree is determined by:
86 All motion/button/expose events take this as the offset when trying to
87 draw the tree. There are also two other related members:
89 tree_view->priv->top_row
90 tree_view->priv->top_row_dy
92 In general _gtk_rbtree_node_find_offset (tree_view->priv->top_row) +
93 tree_view->priv->top_row_dy is the same as tree_view->priv->dy.
94 We have the alternate method so we can update dy when the tree changes.
95 There are two functions:
97 gtk_tree_view_dy_to_top_row
99 gtk_tree_view_top_row_to_dy
101 They are called when the tree's confirmation changes, in order to sync
102 the value appropriately. Note that these two functions sometimes call
103 each other to negotiate a correct value if needed.