org.gnome.gtk

## Class TreeSelection

- Object
- - org.freedesktop.bindings.Pointer
  - - org.freedesktop.bindings.Proxy
    - - org.gnome.glib.Object
      - - org.gnome.gtk.TreeSelection

-     public class TreeSelection
      extends Object

  Manipulate the selection state of a TreeView. Every TreeView has an accompanying TreeSelection object which is used to manage whether or not rows can be selected, and to return to the programmer the current state of which rows are selected, if any.

  TreeSelection can be used to programmatically select rows by either TreeIter or TreePath; see the `selectRow()` methods. For example, to select the first row you could do:

       final TreeSelection selection;

       selection = view.getSelection();
       selection.selectRow(new TreePath("0"));

  Using TreeSelection to determine the currently selected row is fairly straight forward:

       selection.connect(new TreeSelection.Changed() {
           public void onChanged(TreeSelection source) {
               final TreeIter row;

               row = selection.getSelected();

               if (row != null) {
                   // do something!
               }
           }
       });

  Unfortunately, the `TreeSelection.Changed` signal is not entirely deterministic; it is sometimes emitted more than once or for no change at all. You'll need to allow for this in your code.

  Mostly this is an API helper; the underlying documentation notes that these could have all been methods on `GtkTreeView`.

  Since:
    4.0.5
  Author:
    Andrew Cowie, Guillaume Mazoyer

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `TreeSelection.Changed` Emitted when the selection state of the TreeView changes.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `connect(TreeSelection.Changed handler)` Hook up a `TreeSelection.Changed` signal handler.
    `SelectionMode` | `getMode()` Get the mode that is governing selection behaviour on this TreeView.
    `TreeIter` | `getSelected()` Get the selected row from the TreeView.
    `TreePath[]` | `getSelectedRows()` Get the rows currently selected from the TreeView.
    `boolean` | `isSelected(TreePath path)` Return `true` if the currently selected row is pointed by `path`.
    `void` | `selectRow(TreeIter row)` Select a row in the TreeView.
    `void` | `selectRow(TreePath path)` Select a row in the TreeView.
    `void` | `setMode(SelectionMode type)` Set what kinds of selections are allowed.
    `void` | `unselectAll()` Unselect all the rows in the TreeView.

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

      `toString`

    - ### Methods inherited from class Object

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

- - ### Method Detail

    - #### connect

          public void connect(TreeSelection.Changed handler)

      Hook up a `TreeSelection.Changed` signal handler.

    - #### getMode

          public SelectionMode getMode()

      Get the mode that is governing selection behaviour on this TreeView.

    - #### getSelected

          public TreeIter getSelected()

      Get the selected row from the TreeView. Note that this only works when the selection mode is `SINGLE` or `BROWSE`.
      Returns:
        `null` if there is no currently selected row.

    - #### getSelectedRows

          public TreePath[] getSelectedRows()

      Get the rows currently selected from the TreeView. This is specially useful when the selection mode is `MULTIPLE`. Otherwise `getSelected()` offers a more convenient way to obtain the selected row.

      You can use the TreeModel's `getIter()` method to convert the returned TreePaths to the more convenient TreeIter:

           TreePath[] rows;
           TreeSelection selection;
           TreeModel model;

           rows = selection.getSelectedRows();
           for (int i = 0; i < rows.length; ++i) {
               TreeIter row = model.getIter(rows[i]);
               // do something with the row
           }

      Also remember that both TreeIter and TreePath are temporally objects no longer valid once you make any change to the model. Thus, if you plan to modify the model, you may want to convert the returned TreePaths to `TreeRowReferences`.

      Returns:
        An array with the selected rows. If no row is selected, the arrays will be empty.
      Since:
        4.0.7

    - #### isSelected

          public boolean isSelected(TreePath path)

      Return `true` if the currently selected row is pointed by `path`.
      Since:
        4.0.15

    - #### selectRow

          public void selectRow(TreeIter row)

      Select a row in the TreeView. We offer two forms; this one which takes a TreeIter corresponding to a row in the underlying model, and another which takes a TreePath; see `selectRow(TreePath)`.

    - #### selectRow

          public void selectRow(TreePath path)

      Select a row in the TreeView. We offer two forms; this one which takes a TreePath and one which takes a TreeIter; see `selectRow(TreeIter)` for the other. Use this one if you have want to express expressing the row you want selected in abstract, logical form.

    - #### setMode

          public void setMode(SelectionMode type)

      Set what kinds of selections are allowed. The interesting constants you'll use most often are `NONE` and `MULTIPLE` since `SINGLE` is the default. See SelectionMode for the details of the behaviour implied by each option.

    - #### unselectAll

          public void unselectAll()

      Unselect all the rows in the TreeView. Useful to ensure the initial state of the TreeView is that no rows are selected, however you may find you have to wait until after the Window is mapped.