Re: [gtk-list] GtkTree question

[Bolliet Jerome <bolliet in2p3 fr>]

> 
>  hello all,
Hi,

> 
>    sorry if my question is too dumb, but i really can't find a way to make a
>  tree collapse or expand before it's shown... i'm using
>  gtk_tree_item_collapse() or gtk_tree_item_expand() but none of these work
>  (for me). could someone please tell me an order or idea how to accomplish
>  that?
I'm using gtk_tree_item_expand with tree item and there is no problem.

[...]
    subtree = gtk_tree_new();
    gtk_tree_item_set_subtree(GTK_TREE_ITEM(tree_item), subtree);
    gtk_tree_item_expand(tree_item);
    for (i=0; i<3; i++) {
	sprintf(buffer, "Sub Item %d", i);
[...]
That's work for me.
You don't need to use gtk_tree_item_collapse because it's the default
status for a tree item.

>    also, it was a quite a pain to set up the tree as the only help in
>  testgtk source uses recursive function to build it which is rather hard
>  to decode and in my opinion a bit unusable for learning. GTK is really
>  missing docs :( all GTK programmers could stop writing their programs and
>  write docs for GTK as it'd be much easier for programmers to use it :)
I have a doc for gtktree and gtktreeitem. I've made it with the help of
Regis Duchesne <regis@via.ecp.fr>.
Follow a patch for gtk.texi to include gtktree, gtktreeitem documentation.
Comments welcome.

> 
> 	thank u very much,
> 			fuf
> 
Regards,

Jerome Bolliet <bolliet@in2p3.fr>

===============================================================================
3834d3833
< 
3835a3835,3870
> The @code{GtkTree} widget is designed to act as a container (@pxref{GtkContainer}) 
> for widget that must be of @code{GtkTreeItem} (@pxref{GtkTreeItem}) widget.
> The GtkTree widget has the same behaviour as the @code{GtkList} widget 
> (@pxref{GtkList}) but it's not derived from it but directly from the 
> @code{GtkContainer} widget.
> Knowledge of the @code{GtkList} widget is well-timed.
> 
> To create a tree of widget, you can add @code{GtkTreeItem} widgets in a @code{GtkTree}
> widget and you can associate another @code{GtkTree} widget at each @code{GtkTreeItem}
> widget and so on.
> 
> The primary @code{GtkTree} widget is the first one in the tree. This is the root
> of the tree. This is the widget you will have to add to a window in order
> to see the entire tree.
> All @code{GtkTree} widgets in a tree must know the primary @code{GtkTree} widget. 
> This is the purpose of the root_tree field.
> Only the primary @code{GtkTree} owns information like selection and
> configuration data in order to avoid conflicts with other @code{GtkTree} items in
> the tree.
> 
> The selection field of a @code{GtkTree} struct points to a linked list of all items 
> currently selected regardless of their depth in the tree. If there is no items 
> selected, this field is set to 'NULL'. So to know the current selection, 
> read the GTK_TREE()->selection field, but ONLY if you are sure that your 
> @code{GtkTree} item is the primary one !. 
> Anyway, in the tradition of the GTK+ widget set, structures are opaque,
> and it is wiser to use the GTK_TREE_SELECTION() macro to retrieve the current
> selection. 
> In the same manner, do not modify this list since the internal fields are maintained 
> by gtk_tree_* functions.
> 
> The selection_mode of @code{GtkTree} determines the selection facilities of a 
> @code{GtkTree}. 
> You can refer to the @code{GtkList} (@pxref{GtkList}) widget. There is no difference 
> between both of them except that only the selection_mode of your primary 
> @code{GtkTree} widget is used.
3837a3873,3897
> @defopt root_tree
> The @var{root_tree} is a pointer on the primary @code{GtkTree} widget of your
> tree.
> @end defopt
> 
> @defopt selection
> The @var{selection} is a pointer on a doubled linked list of the current
> items selected. Only the @var{selection} of the primary tree widget is usable.
> @end defopt
> 
> @defopt view_mode
> The @var{selection_mode} option specifies how handle the selection facilitie.
> It can be one of @code{GTK_SELECTION_SINGLE}, @code{GTK_SELECTION_BROWSE}, 
> @code{GTK_SELECTION_MULTIPLE} or @code{GTK_SELECTION_EXTENDED}.
> @end defopt
> 
> @defopt view_mode
> The @var{view_line} flag specifies how to view selected items. It can be one of
> @code{GTK_TREE_VIEW_LINE} or @code{GTK_TREE_VIEW_ITEM}.
> @end defopt
> 
> @defopt view_line
> The @var{view_line} flag specifies how to draw the tree. This flag is a boolean
> value. If TRUE, tree draws lines between items and trees.
> @end defopt
3839a3900,3904
> Signals of a GtkTree Widget are identical to @code{GtkList} widget, with the 
> exception of the selection_changed signal. This signal is only used for the 
> primary GtkTree widget. 
> You can add a callback function to other GtkTree widget in your tree but it is 
> useless because they won't be used.
3848c3913
< Create a new @code{GtkTree} object returning the new widget as a pointer to
---
> Creates a new @code{GtkTree} object returning the new widget as a pointer to
3852a3918,3919
> Inserts a newly created @code{GtkTreeItem} @var{child} in the @code{GtkTree} widget 
> @var{tree}. This item is append after all previous appended items.
3855a3923,3924
> Inserts a newly created @code{GtkTreeItem} @var{child} in the @code{GtkTree} widget 
> @var{tree}. This item takes the first place.
3858a3928,3930
> Inserts a newly created @code{GtkTreeItem} @var{child} in the @code{GtkTree} widget 
> @var{tree} in position @var{position}. If @var{position} is less than 0 or greater
> than the number of child in @var{tree}, @var{child} is append at the end.
3861a3934
> Returns the position of @var{child} within @var{tree}. `-1' is returned on failure.
3864a3938,3939
> Removes and destroys tree items from the @var{tree}. A widget is affected if 
> its current position within @var{tree} is in the range specified by START and END.
3867a3943,3948
> Remove and destroy tree items from the @var{tree}. @var{items} is a doubly linked 
> list where each nodes data pointers are expected to point to a directly child of 
> @var{tree}. It is the caller's responsibility to make a call to 
> g_list_free(@var{items}) afterwards. This function DESTROYs all 
> @code{GtkTreeItem} items in the list and if necessary, all @code{GtkTree} items 
> associated with these tree items, and so on, recursively.
3870a3952
> Invokes the select_child signal for the specified @var{child}.
3873a3956,3957
> Invokes the select_child signal for a tree item specified through its current position
> @var{item} within @var{tree}.
3876a3961
> Invokes the unselect_child signal for the specified @var{child}.
3879a3965,3966
> Invokes the unselect_child signal for a tree item specified through its current 
> position @var{item} within @var{tree}.
3882a3970,3973
> Sets @var{tree} to the selection mode @var{mode} which can be of GTK_SELECTION_SINGLE,
> GTK_SELECTION_BROWSE, GTK_SELECTION_MULTIPLE or GTK_SELECTION_EXTENDED.
> You can use this function on any tree item, only the primary tree widget of you 
> @var{tree} is modified.
3885a3977,3986
> Sets the view mode @var{mode} for @var{tree} which can be :
> 
> @itemize @bullet
> @item
> GTK_TREE_VIEW_LINE : The view of a selected item is expanded to the width of your 
> tree. (this is the default mode).
> @item
> GTK_TREE_VIEW_ITEM : The view of a selected item is limited to the width of the user 
> widget in item.
> @end itemize
3888a3990,3993
> Indicates @var{tree} to draw lines between items. The @var{flag} parameter is a 
> boolean value.
> As all parameter, this parameter is stored in the primary tree widget of your 
> @var{tree}.
3891d3995
< 
3901a4006,4039
> A @code{GtkTreeItem} has the same behaviour as a @code{GtkListItem} (@pxref{GtkListItem})
> but is directly derived of a @code{GtkItem} (@pxref{GtkItem}).
> 
> In addition to this, the @code{GtkTreeItem} can be associated with a @code{GtkTree} 
> (@pxref{GtkTree}) widget to form a subtree. 
> It provid some facilities to expand/collapse this subtree.
> 
> A @code{GtkTreeItem} is a composite widget :
> 
> @itemize @bullet
> @item
> a user's widget, child of the container (@code{GtkLabel}, ...)
> @item
> a @code{GtkTree} as subtree.
> @item
> a @code{GtkEventBox} with a @code{GtkPixmap} as button.
> @end itemize
> 
> Usually, a @code{GtkLabel}  (@pxref{GtkLabel}) is used with a @code{GtkTreeItem} 
> but, as a container, you can use any other widget of Gtk+. You can create an empty 
> @code{GtkTreeItem}, your widget, an add this last in your tree widget.
> 
> The @code{GtkEventBox} provid facilities to expand/collapse subtree with a mouse action. 
> This widget is controlled by @code{GtkTreeItem} himself. 
> It appears when a non-empty subtree is associated to the @code{GtkTreeItem}. 
> Depending on @code{GtkTreeItem} status (with/without subtree, expanded/collapsed subtree), 
> this event box emits expand/collapse signal on user action.
> 
> The @code{GtkTree} subtree is not really inside the @code{GtkTreeItem} but 
> is associate with this.
> This widget is automatically destroy when all of its childs are removed.
> 
> You should'nt manipulated these internal @code{GtkTree} and @code{GtkEventBox} widgets. 
> Uses gtk_tree_* and gtk_tree_item_* functions to do this.
3905a4044,4056
> A @code{GtkTreeItem} create two new signals, expand and collapse.
> 
> @deftypefn Signal void GtkTreeItem::expand (GtkTreeItem *@var{item})
> This signal is invoked when a @code{GtkTreeItem} is asked to show his subtree upon request.
> This happens on calls to gtk_tree_item_expand(), or on mouse action
> on the subtree button.
> @end deftypefn
> 
> @deftypefn Signal void GtkTreeItem::collapse (GtkTreeItem *@var{item})
> This signal is invoked when a @code{GtkTreeItem} is asked to hide his subtree upon request.
> This happens on calls to gtk_tree_item_expand(), or on mouse action
> on the subtree button.
> @end deftypefn
3914c4065
< Create a new @code{GtkTreeItem} object returning the new widget as a 
---
> Creates a new @code{GtkTreeItem} object returning the new widget as a 
3919c4070
< Create a new @code{GtkTreeItem} object initializing it with the values in
---
> Creates a new @code{GtkTreeItem} object initializing it with the values in
3924a4076,4077
> Attaches @code{GtkTree} @var{subtree} as subtree of @var{tree_item}. 
> If it has already a subtree, prints a warning and makes nothing.
3927a4081,4083
> This function is basically a wrapper around a call to
> gtk_item_select (GTK_ITEM (@var{tree_item})) which will emit the
> select signal (@pxref{GtkItem} for more info).
3930a4087,4089
> This function is basically a wrapper around a call to
> gtk_item_select (GTK_ITEM (@var{tree_item})) which will emit the
> select signal (@pxref{GtkItem} for more info).
3933a4093
> Invokes the expand signal for the specified @var{tree_item}.
3936a4097
> Invokes the collapse signal for the specified @var{tree_item}.
3939a4101,4102
> Removes and destroys a subtree associate at @var{item}. If there is no such subtree, 
> makes nothing.
3941d4103
<