gtk_tut-12.html

GTK development guide

                           gint     end );
</PRE>
</CODE></BLOCKQUOTE>
<P>Remove the items from position <CODE>start</CODE> to position <CODE>end</CODE>
from a Tree. The same warning about dereferencing applies here, as
gtk_tree_clear_items() simply constructs a list and passes it to
gtk_tree_remove_items().
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_tree_select_item( GtkTree *tree,
                           gint     item );
</PRE>
</CODE></BLOCKQUOTE>
<P>Emits the "select_item" signal for the child at position
<CODE>item</CODE>, thus selecting the child (unless you unselect it in a
signal handler).
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_tree_unselect_item( GtkTree *tree,
                             gint     item );
</PRE>
</CODE></BLOCKQUOTE>
<P>Emits the "unselect_item" signal for the child at position
<CODE>item</CODE>, thus unselecting the child.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_tree_select_child( GtkTree   *tree,
                            GtkWidget *tree_item );
</PRE>
</CODE></BLOCKQUOTE>
<P>Emits the "select_item" signal for the child <CODE>tree_item</CODE>, thus
selecting it.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_tree_unselect_child( GtkTree   *tree,
                              GtkWidget *tree_item );
</PRE>
</CODE></BLOCKQUOTE>
<P>Emits the "unselect_item" signal for the child <CODE>tree_item</CODE>,
thus unselecting it.
<P>
<BLOCKQUOTE><CODE>
<PRE>
gint gtk_tree_child_position( GtkTree   *tree,
                              GtkWidget *child );
</PRE>
</CODE></BLOCKQUOTE>
<P>Returns the position in the tree of <CODE>child</CODE>, unless
<CODE>child</CODE> is not in the tree, in which case it returns -1.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_tree_set_selection_mode( GtkTree          *tree,
                                  GtkSelectionMode  mode );
</PRE>
</CODE></BLOCKQUOTE>
<P>Sets the selection mode, which can be one of <CODE>GTK_SELECTION_SINGLE</CODE> (the
default), <CODE>GTK_SELECTION_BROWSE</CODE>, <CODE>GTK_SELECTION_MULTIPLE</CODE>, or
<CODE>GTK_SELECTION_EXTENDED</CODE>. This is only defined for root trees, which
makes sense, since the root tree "owns" the selection. Setting it for
subtrees has no effect at all; the value is simply ignored.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_tree_set_view_mode( GtkTree         *tree,
                             GtkTreeViewMode  mode ); 
</PRE>
</CODE></BLOCKQUOTE>
<P>Sets the "view mode", which can be either <CODE>GTK_TREE_VIEW_LINE</CODE> (the
default) or <CODE>GTK_TREE_VIEW_ITEM</CODE>.  The view mode propagates from a
tree to its subtrees, and can't be set exclusively to a subtree (this
is not exactly true - see the example code comments).
<P>The term "view mode" is rather ambiguous - basically, it controls the
way the highlight is drawn when one of a tree's children is selected.
If it's <CODE>GTK_TREE_VIEW_LINE</CODE>, the entire TreeItem widget is
highlighted, while for <CODE>GTK_TREE_VIEW_ITEM</CODE>, only the child widget
(i.e., usually the label) is highlighted.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void gtk_tree_set_view_lines( GtkTree *tree,
                              guint    flag );
</PRE>
</CODE></BLOCKQUOTE>
<P>Controls whether connecting lines between tree items are drawn.
<CODE>flag</CODE> is either TRUE, in which case they are, or FALSE, in
which case they aren't.
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkTree *GTK_TREE (gpointer obj);
</PRE>
</CODE></BLOCKQUOTE>
<P>Cast a generic pointer to "GtkTree *".
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkTreeClass *GTK_TREE_CLASS (gpointer class);
</PRE>
</CODE></BLOCKQUOTE>
<P>Cast a generic pointer to "GtkTreeClass *".
<P>
<BLOCKQUOTE><CODE>
<PRE>
gint GTK_IS_TREE (gpointer obj);
</PRE>
</CODE></BLOCKQUOTE>
<P>Determine if a generic pointer refers to a "GtkTree" object.
<P>
<BLOCKQUOTE><CODE>
<PRE>
gint GTK_IS_ROOT_TREE (gpointer obj)
</PRE>
</CODE></BLOCKQUOTE>
<P>Determine if a generic pointer refers to a "GtkTree" object
<EM>and</EM> is a root tree. Though this will accept any pointer, the
results of passing it a pointer that does not refer to a Tree are
undefined and possibly harmful.
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkTree *GTK_TREE_ROOT_TREE (gpointer obj)
</PRE>
</CODE></BLOCKQUOTE>
<P>Return the root tree of a pointer to a "GtkTree" object. The above
warning applies.
<P>
<BLOCKQUOTE><CODE>
<PRE>
GList *GTK_TREE_SELECTION( gpointer obj)
</PRE>
</CODE></BLOCKQUOTE>
<P>Return the selection list of the root tree of a "GtkTree" object. The
above warning applies here, too.
<P>
<H2><A NAME="sec_Tree_Item_Widget"></A> <A NAME="ss12.5">12.5 Tree Item Widget</A>
</H2>

<P>The TreeItem widget, like CListItem, is derived from Item,
which in turn is derived from Bin.  Therefore, the item itself is a
generic container holding exactly one child widget, which can be of
any type. The TreeItem widget has a number of extra fields, but
the only one we need be concerned with is the <CODE>subtree</CODE> field.
<P>The definition for the TreeItem struct looks like this:
<P>
<BLOCKQUOTE><CODE>
<PRE>
struct _GtkTreeItem
{
  GtkItem item;

  GtkWidget *subtree;
  GtkWidget *pixmaps_box;
  GtkWidget *plus_pix_widget, *minus_pix_widget;

  GList *pixmaps;               /* pixmap node for this items color depth */

  guint expanded : 1;
};
</PRE>
</CODE></BLOCKQUOTE>
<P>The <CODE>pixmaps_box</CODE> field is an EventBox which catches clicks on
the plus/minus symbol which controls expansion and collapsing. The
<CODE>pixmaps</CODE> field points to an internal data structure. Since
you can always obtain the subtree of a TreeItem in a (relatively)
type-safe manner with the <CODE>GTK_TREE_ITEM_SUBTREE (Item)</CODE> macro,
it's probably advisable never to touch the insides of a TreeItem
unless you <EM>really</EM> know what you're doing.
<P>Since it is directly derived from an Item it can be treated as such by
using the <CODE>GTK_ITEM (TreeItem)</CODE> macro. A TreeItem usually holds a
label, so the convenience function gtk_list_item_new_with_label() is
provided. The same effect can be achieved using code like the
following, which is actually copied verbatim from
gtk_tree_item_new_with_label():
<P>
<BLOCKQUOTE><CODE>
<PRE>
tree_item = gtk_tree_item_new ();
label_widget = gtk_label_new (label);
gtk_misc_set_alignment (GTK_MISC (label_widget), 0.0, 0.5);

gtk_container_add (GTK_CONTAINER (tree_item), label_widget);
gtk_widget_show (label_widget);
</PRE>
</CODE></BLOCKQUOTE>
<P>As one is not forced to add a Label to a TreeItem, you could
also add an HBox or an Arrow, or even a Notebook (though your
app will likely be quite unpopular in this case) to the TreeItem.
<P>If you remove all the items from a subtree, it will be destroyed and
unparented, unless you reference it beforehand, and the TreeItem
which owns it will be collapsed. So, if you want it to stick around,
do something like the following:
<P>
<BLOCKQUOTE><CODE>
<PRE>
gtk_widget_ref (tree);
owner = GTK_TREE(tree)->tree_owner;
gtk_container_remove (GTK_CONTAINER(tree), item);
if (tree->parent == NULL){
  gtk_tree_item_expand (GTK_TREE_ITEM(owner));
  gtk_tree_item_set_subtree (GTK_TREE_ITEM(owner), tree);
}
else
  gtk_widget_unref (tree);
</PRE>
</CODE></BLOCKQUOTE>
<P>Finally, drag-n-drop <EM>does</EM> work with TreeItems. You just
have to make sure that the TreeItem you want to make into a drag
item or a drop site has not only been added to a Tree, but that
each successive parent widget has a parent itself, all the way back to
a toplevel or dialog window, when you call gtk_widget_dnd_drag_set()
or gtk_widget_dnd_drop_set().  Otherwise, strange things will happen.
<P>
<H3>Signals</H3>

<P>TreeItem inherits the "select", "deselect", and "toggle" signals
from Item. In addition, it adds two signals of its own, "expand"
and "collapse".
<P>
<BLOCKQUOTE><CODE>
<PRE>
void select( GtkItem *tree_item );
</PRE>
</CODE></BLOCKQUOTE>
<P>This signal is emitted when an item is about to be selected, either
after it has been clicked on by the user, or when the program calls
gtk_tree_item_select(), gtk_item_select(), or gtk_tree_select_child().
<P>
<BLOCKQUOTE><CODE>
<PRE>
void deselect( GtkItem *tree_item );
</PRE>
</CODE></BLOCKQUOTE>
<P>This signal is emitted when an item is about to be unselected, either
after it has been clicked on by the user, or when the program calls
gtk_tree_item_deselect() or gtk_item_deselect(). In the case of
TreeItems, it is also emitted by gtk_tree_unselect_child(), and
sometimes gtk_tree_select_child().
<P>
<BLOCKQUOTE><CODE>
<PRE>
void toggle( GtkItem *tree_item );
</PRE>
</CODE></BLOCKQUOTE>
<P>This signal is emitted when the program calls gtk_item_toggle().  The
effect it has when emitted on a TreeItem is to call
gtk_tree_select_child() (and never gtk_tree_unselect_child()) on the
item's parent tree, if the item has a parent tree.  If it doesn't,
then the highlight is reversed on the item.
<P>
<BLOCKQUOTE><CODE>
<PRE>
void expand( GtkTreeItem *tree_item );
</PRE>
</CODE></BLOCKQUOTE>
<P>This signal is emitted when the tree item's subtree is about to be
expanded, that is, when the user clicks on the plus sign next to the
item, or when the program calls gtk_tree_item_expand().
<P>
<BLOCKQUOTE><CODE>
<PRE>
void collapse( GtkTreeItem *tree_item );
</PRE>
</CODE></BLOCKQUOTE>
<P>This signal is emitted when the tree item's subtree is about to be
collapsed, that is, when the user clicks on the minus sign next to the
item, or when the program calls gtk_tree_item_collapse().
<P>
<H3>Functions and Macros</H3>

<P>
<BLOCKQUOTE><CODE>
<PRE>
guint gtk_tree_item_get_type( void );
</PRE>
</CODE></BLOCKQUOTE>
<P>Returns the "GtkTreeItem" type identifier.
<P>
<BLOCKQUOTE><CODE>
<PRE>
GtkWidget* gtk_tree_item_new( void );
</PRE>
</CODE></BLOCKQUOTE>
<P>Create a new TreeItem object. The new widget is returned as a
pointer to a GtkWidget object. NULL is returned on failure.
<P>
<BLOCKQUOTE><CODE>