org.gnome.gtk

## Class TreeModelSort

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.Object
      - - org.gnome.gtk.TreeModel
        - - org.gnome.gtk.TreeModelSort

- All Implemented Interfaces:
    TreeDragSource, TreeSortable

      public class TreeModelSort
      extends TreeModel
      implements TreeDragSource, TreeSortable

  Takes an existing model and creates a new model of it sorted as specified. The data is not copied, but the TreeModel that results from creating a TreeModelSort can be used independently. It listens to and reacts to the signals emitted by the underlying base TreeModel. The end result is that of allowing you to have two different TreeViews with their own sort of the same underlying data set. This is potentially useful if you have a common TreeModel backing a number of different presentations, although you should be cognisant that a point will be reached where it is more efficient to simply have separate models.

  A TreeIter pointing into this TreeModelSort is not valid in the underlying "child" TreeModel. If you need to change data in the base model, use `convertIterToChildIter()`.

  You need to be careful to use the correct TreeModel for TreeIter pointers you receive in callbacks. The scenario that arises more often is this:

       ListStore model;
       TreeModelSort sorted;
       TreeView view;
       TreeSelection selection;

       // usual TreeModel setup
       model = new ListStore(...);

       // then create the sorted one, and use it
       sorted = new TreeModelSort(model);
       view = new TreeView(sorted);
       ...

       // then, later
       selection.connect(new TreeSelection.Changed() {
           public void onChanged(TreeSelection source) {
               final TreeIter row;
               final String str;

               row = selection.getSelected();
               if (row == null) {
                   return;
               }
               str = model.getValue(row, column);
           }
       }

  the problem that arises is that the retrieved TreeIter is not valid in `model`. It's a TreeIter in `sorted`. Your program will crash if you get this wrong. The fix is simple; change it to use the correct TreeModel:

       ...
               str = sorted.getValue(row, column);
       ...

  and things will work fine.

  You don't normally have need of this class. Both ListStore and TreeStore implement TreeSortable already, and there are various sorting tools built into the view side of the TreeView/TreeModel MVC framework, notably TreeViewColumn's `setSortColumn()`. If, however, you are using a `TreeModelFilter`, you will need to wrap it in one of these to make sorting work normally again.

  Since:
    4.0.6
  Author:
    Andrew Cowie

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.gnome.gtk.TreeModel

      `TreeModel.RowChanged`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TreeModelSort(TreeModel base)` Create a new TreeModelSort, wrapping an existing model.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `TreeIter` | `convertIterBaseToSort(TreeIter row)` Given a TreeIter obtained from the underying TreeModel, return one that represents the same row but that will be valid in this TreeModelSort.
    `TreeIter` | `convertIterSortToBase(TreeIter row)` Given a TreeIter valid in this TreeModelSort, figure out the correspnding row in the underlying TreeModel and return a TreeIter that will be valid there.
    `TreeIter` | `convertIterToChildIter(TreeIter row)` Convert a TreeIter pointing into this TreeModelSort into a TreeIter valid in the underlying base TreeModel that is being proxied.
    `TreePath` | `convertPathBaseToSort(TreePath path)` Convert a TreePath identifying a row in the underying TreeModel into the corresponding locator in this TreeModelSort.
    `TreePath` | `convertPathSortToBase(TreePath path)` Convert a TreePath identifying a row in this TreeModelSort into one that points to the corresponding row in the underying TreeModel.
    `void` | `setSortColumn(DataColumn column, SortType ordering)` Specify the column from your (underlying) data model which will be used for sorting this TreeModelSort.

    - ### Methods inherited from class org.gnome.gtk.TreeModel

      `connect, getIter, getIterFirst, getPath, getValue, getValue, getValue, getValue, getValue, getValue, getValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue, setValue`

    - ### Methods inherited from class org.freedesktop.bindings.Pointer

      `toString`

    - ### Methods inherited from class Object

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### TreeModelSort

          public TreeModelSort(TreeModel base)

      Create a new TreeModelSort, wrapping an existing model.
      Since:
        4.0.6

  - ### Method Detail

    - #### convertIterBaseToSort

          public TreeIter convertIterBaseToSort(TreeIter row)

      Given a TreeIter obtained from the underying TreeModel, return one that represents the same row but that will be valid in this TreeModelSort.
      Since:
        4.0.9

    - #### convertIterSortToBase

          public TreeIter convertIterSortToBase(TreeIter row)

      Given a TreeIter valid in this TreeModelSort, figure out the correspnding row in the underlying TreeModel and return a TreeIter that will be valid there.
      Since:
        4.0.9

    - #### convertIterToChildIter

          public TreeIter convertIterToChildIter(TreeIter row)

      Convert a TreeIter pointing into this TreeModelSort into a TreeIter valid in the underlying base TreeModel that is being proxied.

      TODO We need to test the limitations of this, as several people have actually been getting away with not worrying about converting at all, so clearly something isn't quite as expected.

      Since:
        Unstable

    - #### convertPathBaseToSort

          public TreePath convertPathBaseToSort(TreePath path)

      Convert a TreePath identifying a row in the underying TreeModel into the corresponding locator in this TreeModelSort.

      If the row location specified by `path` isn't resolvable in the underlying TreeModel, `null` is returned.

      Since:
        4.0.9

    - #### convertPathSortToBase

          public TreePath convertPathSortToBase(TreePath path)

      Convert a TreePath identifying a row in this TreeModelSort into one that points to the corresponding row in the underying TreeModel.
      Since:
        4.0.9

    - #### setSortColumn

          public void setSortColumn(DataColumn column,
                           SortType ordering)

      Description copied from interface: `TreeSortable`
      Specify the column from your (underlying) data model which will be used for sorting this TreeModelSort. Specify `ASCENDING` or `DESCENDING` order via the `ordering` parameter.
      Specified by:
        `setSortColumn` in interface `TreeSortable`