gtk2/docs/reference/gtk/tree_widget.sgml

<refentry id="TreeWidget" revision="30 Oct 2000">
  <refmeta>
    <refentrytitle>Tree and List Widget Overview</refentrytitle>
    <manvolnum>3</manvolnum>
    <refmiscinfo>GTK Library</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>Tree and List Widget Overview</refname>
    <refpurpose>Overview of <link
    linkend="GtkTreeModel">GtkTreeModel</link>, <link
    linkend="GtkTreeView">GtkTreeView</link>, and other associated widgets</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Overview</title>
    <para>
      To create a tree or list in GTK+, you need to use the <link
      linkend="GtkTreeModel">GtkTreeModel</link> interface, in
      conjunction with the <link
      linkend="GtkTreeView">GtkTreeView</link> widget.
    </para>
    <para>
      This widget is designed around a
      <firstterm>Model/View/Controller</firstterm> design and consists
      of four major parts:
      <simplelist>
	<member>the tree view widget (<structname>GtkTreeView</structname>)</member>
	<member>the view column (<structname>GtkTreeViewColumn</structname>)</member>
	<member>the cell renderers (<structname>GtkCellRenderer</structname> etc.)</member>
	<member>and the model interface (<structname>GtkTreeModel</structname>)</member>
      </simplelist>
      The <emphasis>View</emphasis> is composed of the first three,
	while the last is the <emphasis>Model</emphasis>.  One of the
	prime benefits of the MVC design is that multiple views can be
	created of a single model.  For example, a model mapping the file
	system could be created for a file manager.  Many views could be
	created to display various parts of the file system, but only one
	copy need be kept in memory.
    </para>
  </refsect1>
  <refsect1>
    <title>Simple Example</title>
    <para>
      Here is a simple example of using a <link
      linkend="GtkTreeView">GtkTreeView</link> widget in context of the
      other widgets.  It simply creates a simple model and view, and
      puts them together.  Note that the model is never populated with
      data &mdash; that is left as an exercise for the reader.  More
      information can be found on this in the <link
      linkend="GtkTreeStore">GtkTreeModel</link> section.
      <informalexample><programlisting><![CDATA[
enum
{
  COLUMN_ONE,
  N_COLUMNS
};

{
  GtkTreeStore *model;
  GtkWidget *view;
  GtkTreeViewColumn *column;
  GtkCellRenderer *cell_renderer;

  /* Create a model.  We are using the store model for now, though we
   * could use any other GtkTreeModel */
  model = gtk_tree_store_new (N_COLUMNS, G_TYPE_STRING);

  /* custom function to fill the model with data */
  populate_tree_model (model);

  /* Create a view */
  view = gtk_tree_view_new_with_model (GTK_TREE_MODEL (model));

  /* The view now holds a reference.  We can get rid of our own
   * reference */
  g_object_unref (G_OBJECT (model));

  /* Create a cell render and arbitrarily make it red for demonstration
   * purposes */
  cell_renderer = gtk_cell_renderer_text_new ();
  g_object_set (G_OBJECT (cell_renderer), "foreground", "red", NULL);

  /* Create a column, associating the "text" attribute of the
   * cell_renderer to the first column of the model */
  column = gtk_tree_view_column_new_with_attributes ("title",
						     cell_renderer,
						     "text", COLUMN_ONE,
						     NULL);

  /* Add the column to the view. */
  gtk_tree_view_append_column (GTK_TREE_VIEW (view), column);

  /* Now we can manipulate the view just like any other GTK widget */
  ...
}
]]>
      </programlisting></informalexample>
    </para>
  </refsect1>
</refentry>