6.1.1. Selection Modes

You can use gtk_tree_selection_set_mode to influence the way that selections are handled. There are four selection modes:

• GTK_SELECTION_NONE - no items can be selected

• GTK_SELECTION_SINGLE - no more than one item can be selected

• GTK_SELECTION_BROWSE - exactly one item is always selected

• GTK_SELECTION_MULTIPLE - anything between no item and all items can be selected

6.1.2. Getting the Currently Selected Rows

You can access the currently selected rows either by traversing all selected rows using gtk_tree_selection_selected_foreach or get a GList of tree paths of the selected rows using gtk_tree_selection_get_selected_rows. Note that this function is only available in Gtk+-2.2 and newer, which means that you can't use it or need to reimplement it if you want your application to work with older installations.

If the selection mode you are using is either GTK_SELECTION_SINGLE or GTK_SELECTION_BROWSE, the most convenient way to get the selected row is the function gtk_tree_selection_get_selected, which will return TRUE and fill in the specified tree iter with the selected row (if a row is selected), and return FALSE otherwise. It is used like this:

  ...

  GtkTreeSelection *selection;
  GtkTreeModel     *model;
  GtkTreeIter       iter;

  /* This will only work in single or browse selection mode! */

  selection = gtk_tree_view_get_selection(GTK_TREE_VIEW(view));
  if (gtk_tree_selection_get_selected(selection, &model, &iter))
  {
    gchar *name;

    gtk_tree_model_get (model, &iter, COL_NAME, &name, -1);

    g_print ("selected row is: %s\n", name);

    g_free(name);
  }
  else
  {
    g_print ("no row selected.\n");
  }

  ...

One thing you need to be aware of is that you need to take care when removing rows from the model in a gtk_tree_selection_selected_foreach callback, or when looping through the list that gtk_tree_selection_get_selected_rows returns (because it contains paths, and when you remove rows in the middle, then the old paths will point to either a non-existing row, or to another row than the one selected). You have two ways around this problem: one way is to use the solution to removing multiple rows that has been described above, ie. to get tree row references for all selected rows and then remove the rows one by one; the other solution is to sort the list of selected tree paths so that the last rows come first in the list, so that you remove rows from the end of the list or tree. You cannot remove rows from within a foreach callback in any case, that is simply not allowed.

Here is an example of how to use gtk_tree_selection_selected_foreach:

  ...

  gboolean
  view_selected_foreach_func (GtkTreeModel  *model,
                              GtkTreePath   *path,
                              GtkTreeIter   *iter,
                              gpointer       userdata)
  {
    gchar *name;

    gtk_tree_model_get (model, iter, COL_NAME, &name, -1);

    g_print ("%s is selected\n", name);
  }


  void
  do_something_with_all_selected_rows (GtkWidget *treeview)
  {
    GtkTreeSelection  *selection = gtk_tree_view_get_selection(GTK_TREE_VIEW(treeview));

    gtk_tree_selection_selected_foreach(selection, view_selected_foreach_func, NULL);
  }


  void
  create_view (void)
  {
    GtkWidget         *view;
    GtkTreeSelection  *selection;

    ...

    view = gtk_tree_view_new();

    ...

    selection = gtk_tree_view_get_selection(GTK_TREE_VIEW(view));

    gtk_tree_selection_set_mode(selection, GTK_SELECTION_MULTIPLE);
    ...
  }

  ...

6.1.3. Using Selection Functions

You can set up a custom selection function with gtk_tree_selection_set_select_function. This function will then be called every time a row is going to be selected or unselected (meaning: it will be called before the selection status of that row is changed). Selection functions are commonly used for the following things:

1. ... to keep track of the currently selected items (then you maintain a list of selected items yourself). In this case, note again that your selection function is called before the row's selection status is changed. In other words: if the row is going to be selected, then the boolean path_currently_selected variable that is passed to the selection function is still FALSE. Also note that the selection function might not always be called when a row is removed, so you either have to unselect a row before you remove it to make sure your selection function is called and removes the row from your list, or check the validity of a row when you process the selection list you keep. You should not store tree paths in your self-maintained list of of selected rows, because whenever rows are added or removed or the model is resorted the paths might point to other rows. Use tree row references or other unique means of identifying a row instead.

2. ... to tell Gtk+ whether it is allowed to select or unselect that specific row (you should make sure though that it is otherwise obvious to a user whether a row can be selected or not, otherwise the user will be confused if she just cannot select or unselect a row). This is done by returning TRUE or FALSE in the selection function.

3. ... to take additional action whenever a row is selected or unselected.

Yet another simple example:

  ...

  gboolean
  view_selection_func (GtkTreeSelection *selection,
                       GtkTreeModel     *model,
                       GtkTreePath      *path,
                       gboolean          path_currently_selected,
                       gpointer          userdata)
  {
    GtkTreeIter iter;

    if (gtk_tree_model_get_iter(model, &iter, path))
    {
      gchar *name;

      gtk_tree_model_get(model, &iter, COL_NAME, &name, -1);

      if (!path_currently_selected)
      {
        g_print ("%s is going to be selected.\n", name);
      }
      else
      {
        g_print ("%s is going to be unselected.\n", name);
      }

      g_free(name);
    }

    return TRUE; /* allow selection state to change */
  }


  void
  create_view (void)
  {
    GtkWidget         *view;
    GtkTreeSelection  *selection;

    ...

    view = gtk_tree_view_new();

    ...

    selection = gtk_tree_view_get_selection(GTK_TREE_VIEW(view));

    gtk_tree_selection_set_select_function(selection, view_selection_func, NULL, NULL);
    ...
  }

  ...

6.1.4. Checking Whether a Row is Selected

You can check whether a given row is selected or not using the functions gtk_tree_selection_iter_is_selected. or gtk_tree_selection_path_is_selected. If you want to know all rows that are not selected, for example, you could just traverse the whole list or tree, and use the above functions to check for each row whether it is selected or not.

6.1.5. Selecting and Unselecting Rows

You can select or unselect rows manually with gtk_tree_selection_select_iter, gtk_tree_selection_select_path, gtk_tree_selection_unselect_iter, gtk_tree_selection_unselect_path, gtk_tree_selection_select_all, and gtk_tree_selection_unselect_all should you ever need to do that.

6.1.6. Getting the Number of Selected Rows

Sometimes you want to know the number of rows that are currently selected (for example to set context menu entries active or inactive before you pop up a context menu). If you are using selection mode GTK_SELECTION_SINGLE or GTK_SELECTION_BROWSE, this is trivial to check with gtk_tree_selection_get_selected, which will return either TRUE or FALSE (meaning one selected row or no selected row).

If you are using GTK_SELECTION_MULTIPLE or want a more general approach that works for all selection modes, gtk_tree_selection_count_selected_rows will return the information you are looking for. The only caveat with this function is that it only exists in Gtk+-2.2 and newer, so you will have to reimplement it if you want users with old installations that still use Gtk+-2.0 to be able to use your program as well. Here is a way to reimplement this function:

  static void
  count_foreach_helper (GtkTreeModel *model,
                        GtkTreePath  *path,
                        GtkTreeIter  *iter,
                        gpointer      userdata)
  {
    gint *p_count = (gint*) userdata;

    g_assert (p_count != NULL);

    *p_count = *p_count + 1;
  }

  gint
  my_tree_selection_count_selected_rows (GtkTreeSelection *selection)
  {
    gint count = 0;

    gtk_tree_selection_selected_foreach(selection, count_foreach_helper, &count);

    return count;
  }