1
<!-- ##### SECTION Title ##### -->
4
<!-- ##### SECTION Short_Description ##### -->
5
A widget displaying a hierarchical tree
7
<!-- ##### SECTION Long_Description ##### -->
9
The #GtkCTree widget is used for showing a hierarchical tree
10
to the user, for example a directory tree.
13
The tree is internally represented as a set of #GtkCTreeNode structures.
16
The interface has much in common with the #GtkCList widget: rows (nodes)
17
can be selected by the user etc.
20
Positions in the tree are often indicated by two arguments, a
21
parent and a sibling, both #GtkCTreeNode pointers. If the parent
22
is %NULL, the position is at the root of the tree and if the sibling
23
is %NULL, it will be the last child of parent, otherwise it will be
24
inserted just before the sibling.
27
GtkCTree has been deprecated since GTK+ 2.0 and should not be used
28
in newly written code. Use #GtkTreeView instead.
31
<!-- ##### SECTION See_Also ##### -->
36
<!-- ##### SECTION Stability_Level ##### -->
39
<!-- ##### SECTION Image ##### -->
42
<!-- ##### STRUCT GtkCTree ##### -->
44
The #GtkCTree-struct contains the following user-accessible fields.
45
These fields should be considered read-only; to set the values,
46
use the methods below.
48
<informaltable pgwide="1" frame="none" role="struct">
49
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
53
<entry>#gint <structfield>tree_indent</structfield>;</entry>
54
<entry>The number of pixels each successive level of the tree is
55
indented in the display.</entry>
59
<entry>#gint <structfield>tree_spacing</structfield>;</entry>
60
<entry>The space in pixels between the graphical tree and the text in the
65
<entry>#gint <structfield>tree_column</structfield>;</entry>
66
<entry>The index of the column for which the tree graphics is drawn. </entry>
70
<entry>#GtkCTreeLineStyle <structfield>line_style</structfield>;</entry>
71
<entry>The style in which the lines in the tree graphics are drawn.</entry>
75
<entry>#GtkCTreeExpanderStyle <structfield>expander_style</structfield>;</entry>
76
<entry>The style in which the expander buttons are drawn.</entry>
80
<entry>#GtkCTreeExpanderStyle <structfield>expander_style</structfield>;</entry>
84
</tbody></tgroup></informaltable>
88
<!-- ##### SIGNAL GtkCTree::change-focus-row-expansion ##### -->
90
The row which has the focus is either collapsed or expanded
94
@ctree: the object which received the signal.
95
@expansion: What is being done.
97
<!-- ##### SIGNAL GtkCTree::tree-collapse ##### -->
99
Emitted when a node is collapsed.
102
@ctree: the object which received the signal.
105
<!-- ##### SIGNAL GtkCTree::tree-expand ##### -->
107
Emitted when a node is expanded.
110
@ctree: the object which received the signal.
113
<!-- ##### SIGNAL GtkCTree::tree-move ##### -->
115
Emitted when a node is moved.
118
@ctree: the object which received the signal.
119
@node: The node that is moved.
120
@new_parent: The new parent of the node.
121
@new_sibling: The new sibling of the node.
123
<!-- ##### SIGNAL GtkCTree::tree-select-row ##### -->
125
Emitted when a row is selected.
128
@ctree: the object which received the signal.
129
@node: The node corresponding to the selected row.
130
@column: The column which was selected.
132
<!-- ##### SIGNAL GtkCTree::tree-unselect-row ##### -->
134
Emitted when a node is unselected.
137
@ctree: the object which received the signal.
138
@node: The node corresponding to the selected row.
141
<!-- ##### ARG GtkCTree:expander-style ##### -->
143
The style of the expander buttons.
146
<!-- ##### ARG GtkCTree:indent ##### -->
148
The number of pixels to indent the tree levels.
151
<!-- ##### ARG GtkCTree:line-style ##### -->
153
The style of the lines in the tree graphic.
156
<!-- ##### ARG GtkCTree:n-columns ##### -->
158
The number of columns in the tree.
161
<!-- ##### ARG GtkCTree:show-stub ##### -->
166
<!-- ##### ARG GtkCTree:spacing ##### -->
168
The number of pixels between the tree and the columns.
171
<!-- ##### ARG GtkCTree:tree-column ##### -->
173
The column in which the actual tree graphic appears.
176
<!-- ##### MACRO GTK_CTREE_ROW ##### -->
178
Used to get the #GtkCTreeRow structure corresponding to the given #GtkCTreeNode.
184
<!-- ##### MACRO GTK_CTREE_NODE ##### -->
192
<!-- ##### MACRO GTK_CTREE_NODE_NEXT ##### -->
200
<!-- ##### MACRO GTK_CTREE_NODE_PREV ##### -->
208
<!-- ##### MACRO GTK_CTREE_FUNC ##### -->
216
<!-- ##### ENUM GtkCTreePos ##### -->
218
A value specifying the position of a new node relative to an old one.
220
<informaltable pgwide="1" frame="none" role="enum">
221
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
225
<entry>GTK_CTREE_POS_BEFORE</entry>
226
<entry>As a sibling, before the specified node.</entry>
230
<entry>GTK_CTREE_POS_AS_CHILD</entry>
231
<entry>As a child of the specified node.</entry>
235
<entry>GTK_CTREE_POS_AFTER</entry>
236
<entry>As a sibling, after the specified node.</entry>
239
</tbody></tgroup></informaltable>
243
@GTK_CTREE_POS_BEFORE:
244
@GTK_CTREE_POS_AS_CHILD:
245
@GTK_CTREE_POS_AFTER:
247
<!-- ##### ENUM GtkCTreeLineStyle ##### -->
249
The appearance of the lines in the tree graphics.
251
<informaltable pgwide="1" frame="none" role="enum">
252
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
256
<entry>GTK_CTREE_LINES_NONE</entry>
257
<entry>No lines.</entry>
261
<entry>GTK_CTREE_LINES_SOLID</entry>
262
<entry>Solid lines.</entry>
266
<entry>GTK_CTREE_LINES_DOTTED</entry>
267
<entry>Dotted lines.</entry>
271
<entry>GTK_CTREE_LINES_TABBED</entry>
272
<entry>FIXME.</entry>
275
</tbody></tgroup></informaltable>
280
@GTK_CTREE_LINES_NONE:
281
@GTK_CTREE_LINES_SOLID:
282
@GTK_CTREE_LINES_DOTTED:
283
@GTK_CTREE_LINES_TABBED:
285
<!-- ##### ENUM GtkCTreeExpanderStyle ##### -->
287
The appearance of the expander buttons, i.e. the small buttons
288
which expand or contract parts of the tree when pressed.
291
<informaltable pgwide="1" frame="none" role="enum">
292
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
296
<entry>GTK_CTREE_EXPANDER_NONE</entry>
297
<entry>No expanders.</entry>
301
<entry>GTK_CTREE_EXPANDER_SQUARE</entry>
302
<entry>Square expanders.</entry>
306
<entry>GTK_CTREE_EXPANDER_TRIANGLE</entry>
307
<entry>Triangular expanders.</entry>
311
<entry>GTK_CTREE_EXPANDER_CIRCULAR</entry>
312
<entry>Round expanders.</entry>
315
</tbody></tgroup></informaltable>
320
@GTK_CTREE_EXPANDER_NONE:
321
@GTK_CTREE_EXPANDER_SQUARE:
322
@GTK_CTREE_EXPANDER_TRIANGLE:
323
@GTK_CTREE_EXPANDER_CIRCULAR:
325
<!-- ##### ENUM GtkCTreeExpansionType ##### -->
327
How to expand or collapse a part of a tree.
329
<informaltable pgwide="1" frame="none" role="enum">
330
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
334
<entry>GTK_CTREE_EXPANSION_EXPAND</entry>
335
<entry>Expand this node.</entry>
339
<entry>GTK_CTREE_EXPANSION_EXPAND_RECURSIVE</entry>
340
<entry>Expand this node and everything below it in the hierarchy.</entry>
344
<entry>GTK_CTREE_EXPANSION_COLLAPSE</entry>
345
<entry>Collapse this node.</entry>
349
<entry>GTK_CTREE_EXPANSION_COLLAPSE_RECURSIVE</entry>
350
<entry>Collapse this node and everything below it in the hierarchy.</entry>
354
<entry>GTK_CTREE_EXPANSION_TOGGLE</entry>
355
<entry>Toggle this node (i.e. expand if collapsed and vice versa).</entry>
359
<entry>GTK_CTREE_EXPANSION_TOGGLE_RECURSIVE</entry>
360
<entry>Toggle this node and everything below it in the hierarchy.</entry>
364
</tbody></tgroup></informaltable>
369
@GTK_CTREE_EXPANSION_EXPAND:
370
@GTK_CTREE_EXPANSION_EXPAND_RECURSIVE:
371
@GTK_CTREE_EXPANSION_COLLAPSE:
372
@GTK_CTREE_EXPANSION_COLLAPSE_RECURSIVE:
373
@GTK_CTREE_EXPANSION_TOGGLE:
374
@GTK_CTREE_EXPANSION_TOGGLE_RECURSIVE:
376
<!-- ##### USER_FUNCTION GtkCTreeFunc ##### -->
378
A generic callback type to do something with a particular node.
381
@ctree: The #GtkCTree object.
382
@node: The #GtkCTreeNode in the tree.
383
@data: The user data associated with the node.
386
<!-- ##### USER_FUNCTION GtkCTreeGNodeFunc ##### -->
399
<!-- ##### USER_FUNCTION GtkCTreeCompareDragFunc ##### -->
411
<!-- ##### STRUCT GtkCTreeRow ##### -->
413
A structure representing a single row in the tree graph.
414
The values inside the structure should be considered read-only.
415
This structure is derived from the #GtkCListRow structure.
417
<informaltable pgwide="1" frame="none" role="struct">
418
<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
422
<entry>#GtkCTreeNode *<structfield>parent</structfield>;</entry>
423
<entry>The parent node of the node corresponding to this row.
428
<entry>#GtkCTreeNode *<structfield>sibling</structfield>;</entry>
429
<entry>The next sibling node of the node corresponding to this row.
434
<entry>#GtkCTreeNode *<structfield>children</structfield>;</entry>
435
<entry>The first child node corresponding to this row; to access
436
the other children, just use the siblings of that node.
441
<entry>#GdkPixmap *<structfield>pixmap_closed</structfield>;</entry>
442
<entry> The pixmap to be shown when the node is collapsed.
447
<entry>#GdkBitmap *<structfield>mask_closed</structfield>;</entry>
448
<entry> The mask for the above pixmap.
453
<entry>#GdkPixmap *<structfield>pixmap_opened</structfield>;</entry>
454
<entry> The pixmap to be shown when the node is expanded.
459
<entry>#GdkBitmap *<structfield>mask_opened</structfield>;</entry>
460
<entry> The mask for the above pixmap.
465
<entry>#guint16 <structfield>level</structfield>;</entry>
466
<entry>The level of this node in the tree.
472
<entry>#guint <structfield>is_leaf</structfield> : 1;</entry>
473
<entry>Whether this row is a leaf.
478
<entry>#guint <structfield>expanded</structfield> : 1;</entry>
479
<entry>Whether the children of this row are visible.
482
</tbody></tgroup></informaltable>
498
<!-- ##### STRUCT GtkCTreeNode ##### -->
500
This structure is opaque - you should use the
501
macros #GTK_CTREE_ROW, #GTK_CTREE_NODE_NEXT etc. as well
502
as the functions below to access it.
507
<!-- ##### MACRO GTK_TYPE_CTREE_NODE ##### -->
514
<!-- ##### FUNCTION gtk_ctree_new_with_titles ##### -->
516
Create a new #GtkCTree widget with the given titles for the columns.
519
@columns: Number of columns.
520
@tree_column: Which column has the tree graphic; 0 = leftmost.
521
@titles: The titles for the columns.
522
@Returns: The #GtkCTree widget.
525
<!-- ##### FUNCTION gtk_ctree_new ##### -->
527
Create a new #GtkCTree widget.
530
@columns: Number of columns.
531
@tree_column: Which columns has the tree graphic.
532
@Returns: The new #GtkCTree widget.
535
<!-- ##### FUNCTION gtk_ctree_insert_node ##### -->
537
Insert a new node to the tree. The position is specified through
538
the parent-sibling notation, as explained in the introduction above.
541
@ctree: The #GtkCTree widget.
542
@parent: The parent node to be.
543
@sibling: The sibling node to be.
544
@text: The texts to be shown in each column.
545
@spacing: The extra space between the pixmap and the text.
546
@pixmap_closed: The pixmap to be used when the node is collapsed. Can be %NULL.
547
@mask_closed: The mask for the above pixmap. Can be %NULL.
548
@pixmap_opened: The pixmap to be used when the children are visible. Can be %NULL.
549
@mask_opened: The mask for the above pixmap. Can be %NULL.
550
@is_leaf: Whether this node is going to be a leaf.
551
@expanded: Whether this node should start out expanded or not.
555
<!-- ##### FUNCTION gtk_ctree_remove_node ##### -->
557
Remove the node and all nodes underneath it from the tree.
561
@node: The node to be removed.
564
<!-- ##### FUNCTION gtk_ctree_insert_gnode ##### -->
578
<!-- ##### FUNCTION gtk_ctree_export_to_gnode ##### -->
592
<!-- ##### FUNCTION gtk_ctree_post_recursive ##### -->
594
Recursively apply a function to all nodes of the tree at or below a certain
596
The function is called for each node after it has been called
597
for that node's children.
601
@node: The node where to start. %NULL means to start at the root.
602
@func: The function to apply to each node.
603
@data: A closure argument given to each invocation of the function.
606
<!-- ##### FUNCTION gtk_ctree_post_recursive_to_depth ##### -->
608
Recursively apply a function to nodes up to a certain depth.
609
The function is called for each node after it has been called
610
for that node's children.
614
@node: The node where to start.
615
@depth: The maximum absolute depth for applying the function. If depth is negative, this function just calls #gtk_ctree_post_recursive.
616
@func: The function to apply to each node.
617
@data: A closure argument given to each invocation of the function.
620
<!-- ##### FUNCTION gtk_ctree_pre_recursive ##### -->
622
Recursively apply a function to all nodes of the tree at or below a certain
624
The function is called for each node after it has been called
629
@node: The node where to start. %NULL means to start at the root.
630
@func: The function to apply to each node.
631
@data: A closure argument given to each invocation of the function.
634
<!-- ##### FUNCTION gtk_ctree_pre_recursive_to_depth ##### -->
636
Recursively apply a function to nodes up to a certain depth.
637
The function is called for each node after it has been called
638
for that node's children.
642
@node: The node where to start.
643
@depth: The maximum absolute depth for applying the function. If depth is negative, this function just calls #gtk_ctree_post_recursive.
644
@func: The function to apply to each node.
645
@data: A closure argument given to each invocation of the function.
648
<!-- ##### FUNCTION gtk_ctree_is_viewable ##### -->
650
This function checks whether the given node is viewable i.e. so that
651
all of its parent nodes are expanded. This is different from being
652
actually visible: the node can be viewable but outside the scrolling
658
@Returns: Whether the node is viewable.
661
<!-- ##### FUNCTION gtk_ctree_last ##### -->
663
Returns the last child of the last child of the last child...
672
<!-- ##### FUNCTION gtk_ctree_find_node_ptr ##### -->
674
Finds the node pointer given a #GtkCTreeRow structure.
679
@Returns: The node pointer.
682
<!-- ##### FUNCTION gtk_ctree_find ##### -->
688
@node: The node to start searching from. May be %NULL.
690
@Returns: True if @child is on some level a child (grandchild...) of the @node.
693
<!-- ##### FUNCTION gtk_ctree_is_ancestor ##### -->
701
@Returns: True is @node is an ancestor of @child.
704
<!-- ##### FUNCTION gtk_ctree_find_by_row_data ##### -->
706
Finds a node in the tree under @node that has the given user data pointer.
712
@Returns: The node, or %NULL if not found.
715
<!-- ##### FUNCTION gtk_ctree_find_all_by_row_data ##### -->
717
Finds all nodes in the tree under @node that have the given user data pointer.
723
@Returns: A list of nodes that have the given data pointer.
726
<!-- ##### FUNCTION gtk_ctree_find_by_row_data_custom ##### -->
728
Find the first node under @node whose row data pointer fulfills
733
@node: The node where to start searching.
734
@data: User data for the criterion function.
735
@func: The criterion function.
736
@Returns: The first node found.
739
<!-- ##### FUNCTION gtk_ctree_find_all_by_row_data_custom ##### -->
741
Find all nodes under @node whose row data pointer fulfills
747
@node: The node where to start searching.
748
@data: User data for the criterion function.
749
@func: The criterion function.
750
@Returns: A list of all nodes found.
753
<!-- ##### FUNCTION gtk_ctree_is_hot_spot ##### -->
760
@Returns: True if the given coordinates lie on an expander button.
763
<!-- ##### FUNCTION gtk_ctree_move ##### -->
765
Move a node in the tree to another location.
769
@node: The node to be moved.
770
@new_parent: The new parent-to-be of the node.
771
@new_sibling: The new sibling-to-be of the node.
774
<!-- ##### FUNCTION gtk_ctree_expand ##### -->
783
<!-- ##### FUNCTION gtk_ctree_expand_recursive ##### -->
785
Expand one node and all nodes underneath.
792
<!-- ##### FUNCTION gtk_ctree_expand_to_depth ##### -->
794
Expand a node and its children up to the depth given.
799
@depth: The (absolute) depth up to which to expand nodes.
802
<!-- ##### FUNCTION gtk_ctree_collapse ##### -->
811
<!-- ##### FUNCTION gtk_ctree_collapse_recursive ##### -->
813
Collapse one node and all its subnodes.
820
<!-- ##### FUNCTION gtk_ctree_collapse_to_depth ##### -->
822
Collapse a node and its children up to the depth given.
827
@depth: The (absolute) depth up to which to collapse nodes.
830
<!-- ##### FUNCTION gtk_ctree_toggle_expansion ##### -->
832
Toggle a node, i.e. if it is collapsed, expand it and vice versa.
839
<!-- ##### FUNCTION gtk_ctree_toggle_expansion_recursive ##### -->
841
Toggle the expansion of a node and all its children.
848
<!-- ##### FUNCTION gtk_ctree_select ##### -->
850
Cause the given node to be selected and emit the appropriate signal.
857
<!-- ##### FUNCTION gtk_ctree_select_recursive ##### -->
859
Cause the given node and its subnodes to be selected and emit the appropriate signal(s).
866
<!-- ##### FUNCTION gtk_ctree_unselect ##### -->
868
Unselect the given node and emit the appropriate signal.
875
<!-- ##### FUNCTION gtk_ctree_unselect_recursive ##### -->
877
Unselect the given node and its subnodes and emit the appropriate signal(s).
884
<!-- ##### FUNCTION gtk_ctree_real_select_recursive ##### -->
886
The function that implements both #gtk_ctree_select_recursive and
887
#gtk_ctree_unselect_recursive.
892
@state: True for selecting, false for unselecting.
895
<!-- ##### FUNCTION gtk_ctree_node_set_text ##### -->
897
Set the text in a node.
902
@column: The column whose text to change.
906
<!-- ##### FUNCTION gtk_ctree_node_set_pixmap ##### -->
918
<!-- ##### FUNCTION gtk_ctree_node_set_pixtext ##### -->
932
<!-- ##### FUNCTION gtk_ctree_set_node_info ##### -->
934
Change the information. Most parameters correspond
935
to the parameters of #gtk_ctree_insert_node.
940
@text: The text to be in the tree column.
950
<!-- ##### FUNCTION gtk_ctree_node_set_shift ##### -->
952
Shift the given cell the given amounts in pixels.
962
<!-- ##### FUNCTION gtk_ctree_node_set_selectable ##### -->
969
@selectable: Whether this node can be selected by the user.
972
<!-- ##### FUNCTION gtk_ctree_node_get_selectable ##### -->
979
@Returns: Whether this node can be selected by the user.
982
<!-- ##### FUNCTION gtk_ctree_node_get_cell_type ##### -->
990
@Returns: The type of the given cell.
993
<!-- ##### FUNCTION gtk_ctree_node_get_text ##### -->
1001
@text: If nonnull, the pointer to the text string is assigned to *@text.
1002
@Returns: True if the given cell has text in it.
1005
<!-- ##### FUNCTION gtk_ctree_node_get_pixmap ##### -->
1013
@pixmap: If nonnull, the pointer to the pixmap is returned through this.
1014
@mask: If nonnull, the pointer to the mask is returned through this.
1015
@Returns: True if the given cell contains a pixmap.
1018
<!-- ##### FUNCTION gtk_ctree_node_get_pixtext ##### -->
1020
Get the parameters of a cell containing both a pixmap and text.
1033
<!-- ##### FUNCTION gtk_ctree_get_node_info ##### -->
1035
Get information corresponding to a node.
1036
Any of the return parameters can be null.
1052
<!-- ##### FUNCTION gtk_ctree_node_set_row_style ##### -->
1054
Set the style of a row.
1062
<!-- ##### FUNCTION gtk_ctree_node_get_row_style ##### -->
1064
Get the style of a row.
1072
<!-- ##### FUNCTION gtk_ctree_node_set_cell_style ##### -->
1074
Set the style of an individual cell.
1083
<!-- ##### FUNCTION gtk_ctree_node_get_cell_style ##### -->
1085
Get the style of an individual cell.
1094
<!-- ##### FUNCTION gtk_ctree_node_set_foreground ##### -->
1104
<!-- ##### FUNCTION gtk_ctree_node_set_background ##### -->
1114
<!-- ##### FUNCTION gtk_ctree_node_set_row_data ##### -->
1116
Set the custom data associated with a node.
1124
<!-- ##### FUNCTION gtk_ctree_node_set_row_data_full ##### -->
1126
This is the full interface to setting row data, so that a destructor
1127
can be given for the data.
1133
@destroy: The routine to be called when @data is no longer needed.
1136
<!-- ##### FUNCTION gtk_ctree_node_get_row_data ##### -->
1146
<!-- ##### FUNCTION gtk_ctree_node_moveto ##### -->
1148
This function makes the given column of the given node visible by
1153
@node: The node to be made visible.
1154
@column: The column to be made visible.
1155
@row_align: Where in the window the row should appear.
1156
@col_align: Where in the window the column should appear.
1159
<!-- ##### FUNCTION gtk_ctree_node_is_visible ##### -->
1166
@Returns: True if the node is currently inside the bounds of the window.
1167
Note that this function can return true even if the node is not
1168
viewable, if the node's ancestor is visible.
1171
<!-- ##### FUNCTION gtk_ctree_set_indent ##### -->
1177
@indent: The number of pixels to shift the levels of the tree.
1180
<!-- ##### FUNCTION gtk_ctree_set_spacing ##### -->
1182
The spacing between the tree graphic and the actual node content.
1189
<!-- ##### MACRO gtk_ctree_set_reorderable ##### -->
1198
<!-- ##### FUNCTION gtk_ctree_set_line_style ##### -->
1207
<!-- ##### FUNCTION gtk_ctree_set_expander_style ##### -->
1216
<!-- ##### FUNCTION gtk_ctree_set_drag_compare_func ##### -->
1225
<!-- ##### FUNCTION gtk_ctree_sort_node ##### -->
1227
Sort the children of a node. See #GtkCList for how to set the sorting
1235
<!-- ##### FUNCTION gtk_ctree_sort_recursive ##### -->
1237
Sort the descendants of a node. See #GtkCList for how to set the sorting
1245
<!-- ##### FUNCTION gtk_ctree_node_nth ##### -->
1252
@Returns: The node corresponding to the @row th row.
1255
<!-- ##### FUNCTION gtk_ctree_set_show_stub ##### -->
added
removed
docs/reference/gtk/tmpl/gtkctree.sgml
