Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tree_widget.sgml

   1 <refentry id="TreeWidget" revision="30 Oct 2000">
   2   <refmeta>
   3     <refentrytitle>Tree and List Widget Overview</refentrytitle>
   4     <manvolnum>3</manvolnum>
   5     <refmiscinfo>GTK Library</refmiscinfo>
   6   </refmeta>
   7
   8   <refnamediv>
   9     <refname>Tree and List Widget Overview</refname>
  10     <refpurpose>Overview of <link
  11     linkend="GtkTreeModel">GtkTreeModel</link>, <link
  12     linkend="GtkTreeView">GtkTreeView</link>, and other associated widgets</refpurpose>
  13   </refnamediv>
  14
  15   <refsect1>
  16     <title>Overview</title>
  17     <para>
  18       To create a tree or list in GTK+, you need to use the <link
  19       linkend="GtkTreeModel">GtkTreeModel</link> interface, in
  20       conjunction with the <link
  21       linkend="GtkTreeView">GtkTreeView</link> widget.
  22     </para>
  23     <para>
  24       This widget is designed around a
  25       <firstterm>Model/View/Controller</firstterm> design and consists
  26       of four major parts:
  27       <simplelist>
  28         <member>the tree view widget (<structname>GtkTreeView</structname>)</member>
  29         <member>the view column (<structname>GtkTreeViewColumn</structname>)</member>
  30         <member>the cell renderers (<structname>GtkCellRenderer</structname> etc.)</member>
  31         <member>and the model interface (<structname>GtkTreeModel</structname>)</member>
  32       </simplelist>
  33       The <emphasis>View</emphasis> is composed of the first three,
  34         while the last is the <emphasis>Model</emphasis>.  One of the
  35         prime benefits of the MVC design is that multiple views can be
  36         created of a single model.  For example, a model mapping the file
  37         system could be created for a file manager.  Many views could be
  38         created to display various parts of the file system, but only one
  39         copy need be kept in memory.
  40     </para>
  41   </refsect1>
  42   <refsect1>
  43     <title>Simple Example</title>
  44     <para>
  45       Here is a simple example of using a <link
  46       linkend="GtkTreeView">GtkTreeView</link> widget in context of the
  47       other widgets.  It simply creates a simple model and view, and
  48       puts them together.  Note that the model is never populated with
  49       data &mdash; that is left as an exercise for the reader.  More
  50       information can be found on this in the <link
  51       linkend="GtkTreeStore">GtkTreeModel</link> section.
  52       <informalexample><programlisting><![CDATA[
  53 {
  54   GtkTreeStore *model;
  55   GtkWidget *view;
  56   GtkTreeViewColumn *column;
  57   GtkCellRenderer *cell_renderer;
  58
  59   /* Create a model.  We are using the store model for now, though we
  60    * could use any other GtkTreeModel */
  61   model = gtk_tree_store_new_with_values (1, G_TYPE_STRING);
  62   populate_tree_model (model);
  63
  64   /* Create a view */
  65   view = gtk_tree_view_new_with_model (GTK_TREE_MODEL (model));
  66
  67   /* The view now holds a reference.  We can get rid of our own
  68    * reference */
  69   g_object_unref (G_OBJECT (model));
  70
  71   /* Create a cell render and arbitrarily make it red for demonstartion
  72    *purposes */
  73   cell_renderer = gtk_cell_renderer_text_new ();
  74   g_object_set (G_OBJECT (cell_renderer), "foreground", "red", NULL);
  75
  76   /* Create a column, associating the "text" attribute of the
  77    * cell_renderer to the first column of the model */
  78   column = gtk_tree_view_column_new_with_attributes ("title",
  79                                                      cell_renderer,
  80                                                      "text", 0,
  81                                                      NULL);
  82
  83   /* Add the column to the view. */
  84   gtk_tree_view_append_column (GTK_TREE_VIEW (view), column);
  85 }
  86 ]]>
  87       </programlisting></informalexample>
  88     </para>
  89   </refsect1>
  90 </refentry>