The View
| Chapter 8. The TreeView widget |

## The View

The View is the actual widget (`Gtk::TreeView`) that displays the model (`Gtk::TreeModel`) data and allows the user to interact with it. The View can show all of the model's columns, or just some, and it can show them in various ways.

Reference

### Using a Model

You can specify a `Gtk::TreeModel` when constructing the `Gtk::TreeView`, or you can use the `set_model()` method, like so:

    m_TreeView.set_model(m_refListStore);

### Adding View Columns

You can use the `append_column()` method to tell the View that it should display certain Model columns, in a certain order, with a certain column title.

    m_TreeView.append_column("Messages", m_Columns.m_col_text);

When using this simple `append_column()` override, the `TreeView` will display the model data with an appropriate `CellRenderer`. For instance, strings and numbers are shown in a simple `Gtk::Entry` widget, and booleans are shown in a `Gtk::CheckButton`. This is usually what you need. For other column types you must either connect a callback that converts your type into a string representation, with `TreeViewColumn::set_cell_data_func()`, or derive a custom `CellRenderer`. Note that (unsigned) short is not supported by default - You could use (unsigned) int or (unsigned) long as the column type instead.

### More than one Model Column per View Column

To render more than one model column in a view column, you need to create the `TreeView::Column` widget manually, and use `pack_start()` to add the model columns to it.

Then use `append_column()` to add the view Column to the View. Notice that `Gtk::View::append_column()` is overridden to accept either a prebuilt `Gtk::View::Column` widget, or just the `TreeModelColumn` from which it generates an appropriate `Gtk::View::Column` widget.

Here is some example code from `demos/gtk-demo/example_stockbrowser.cc`, which has a pixbuf icon and a text name in the same column:

    Gtk::TreeView::Column* pColumn =
        Gtk::manage( new Gtk::TreeView::Column("Symbol") );

    // m_columns.icon and m_columns.symbol are columns in the model.
    // pColumn is the column in the TreeView:
    pColumn->pack_start(m_columns.icon, false); //false = don't expand.
    pColumn->pack_start(m_columns.symbol);

    m_TreeView.append_column(*pColumn);

### Specifying CellRenderer details

The default `CellRenderers` and their default behaviour will normally suffice, but you might occasionally need finer control. For instance, this example code from `demos/gtk-demo/example_treestore.cc`, manually constructs a `Gtk::CellRenderer` widget and instructs it to render the data from various model columns through various aspects of its appearance.

    Gtk::CellRendererToggle* pRenderer =
        Gtk::manage( new Gtk::CellRendererToggle() );
    int cols_count = m_TreeView.append_column("Alex", *pRenderer);
    Gtk::TreeViewColumn* pColumn = m_TreeView.get_column(cols_count-1);
    if(pColumn)
    {
      pColumn->add_attribute(pRenderer->property_active(),
          m_columns.alex);
      pColumn->add_attribute(pRenderer->property_visible(),
          m_columns.visible);
      pColumn->add_attribute(pRenderer->property_activatable(),
          m_columns.world);

You can also connect to `CellRenderer` signals to detect user actions. For instance:

    Gtk::CellRendererToggle* pRenderer =
        Gtk::manage( new Gtk::CellRendererToggle() );
    pRenderer->signal_toggled().connect(
        sigc::bind( sigc::mem_fun(*this,
            &Example_TreeView_TreeStore::on_cell_toggled), m_columns.dave)
    );

### Editable Cells

#### Automatically-stored editable cells.

Cells in a `TreeView` can be edited in-place by the user. To allow this, use the `Gtk::TreeView` `insert_column_editable()` and `append_column_editable()` methods instead of `insert_column()` and `append_column()`. When these cells are edited the new values will be stored immediately in the Model. Note that these methods are templates which can only be instantiated for simple column types such as `Glib::ustring`, int, and long.

#### Implementing custom logic for editable cells.

However, you might not want the new values to be stored immediately. For instance, maybe you want to restrict the input to certain characters or ranges of values.

To achieve this, you should use the normal `Gtk::TreeView` `insert_column()` and `append_column()` methods, then use `get_column_cell_renderer()` to get the `Gtk::CellRenderer` used by that column.

You should then cast that `Gtk::CellRenderer*` to the specific `CellRenderer` that you expect, so you can use specific API.

For instance, for a CellRendererText, you would set the cell's editable property to true, like so:

    cell.property_editable() = true;

For a CellRendererToggle, you would set the activatable property instead.

You can then connect to the appropriate "edited" signal. For instance, connect to `Gtk::CellRendererText::signal_edited()`, or `Gtk::CellRendererToggle::signal_toggled()`. If the column contains more than one `CellRenderer` then you will need to use `Gtk::TreeView::get_column()` and then call `get_cell_renderers()` on that view Column.

In your signal handler, you should examine the new value and then store it in the Model if that is appropriate for your application.

Chapter 8. The TreeView widget |  | Iterating over Model Rows