### Interface

# Gtk SelectionModel

since: 4.0

#### Description [src]

    interface Gtk.SelectionModel : Gio.ListModel

`GtkSelectionModel` is an interface that add support for selection to list models.

This support is then used by widgets using list models to add the ability to select and unselect various items.

GTK provides default implementations of the most common selection modes such as `GtkSingleSelection`, so you will only need to implement this interface if you want detailed control about how selections should be handled.

A `GtkSelectionModel` supports a single boolean per item indicating if an item is selected or not. This can be queried via `gtk_selection_model_is_selected()`. When the selected state of one or more items changes, the model will emit the `GtkSelectionModel::selection-changed` signal by calling the `gtk_selection_model_selection_changed()` function. The positions given in that signal may have their selection state changed, though that is not a requirement. If new items added to the model via the `GListModel::items-changed` signal are selected or not is up to the implementation.

Note that items added via `GListModel::items-changed` may already be selected and no `GtkSelectionModel::selection-changed` will be emitted for them. So to track which items are selected, it is necessary to listen to both signals.

Additionally, the interface can expose functionality to select and unselect items. If these functions are implemented, GTK’s list widgets will allow users to select and unselect items. However, `GtkSelectionModel`s are free to only implement them partially or not at all. In that case the widgets will not support the unimplemented operations.

When selecting or unselecting is supported by a model, the return values of the selection functions do not indicate if selection or unselection happened. They are only meant to indicate complete failure, like when this mode of selecting is not supported by the model.

Selections may happen asynchronously, so the only reliable way to find out when an item was selected is to listen to the signals that indicate selection.

Available since: 4.0

#### Prerequisite

In order to implement SelectionModel, your type must inherit from`GListModel`.

#### Implementations

- GtkMultiSelection
- GtkNoSelection
- GtkSingleSelection

#### Instance methods

###### gtk_selection_model_get_selection

Gets the set containing all currently selected items in the model.

since: 4.0

###### gtk_selection_model_get_selection_in_range

Gets the set of selected items in a range.

since: 4.0

###### gtk_selection_model_is_selected

Checks if the given item is selected.

since: 4.0

###### gtk_selection_model_select_all

Requests to select all items in the model.

since: 4.0

###### gtk_selection_model_select_item

Requests to select an item in the model.

since: 4.0

###### gtk_selection_model_select_range

Requests to select a range of items in the model.

since: 4.0

###### gtk_selection_model_selection_changed

Helper function for implementations of `GtkSelectionModel`.

since: 4.0

###### gtk_selection_model_set_selection

Make selection changes.

since: 4.0

###### gtk_selection_model_unselect_all

Requests to unselect all items in the model.

since: 4.0

###### gtk_selection_model_unselect_item

Requests to unselect an item in the model.

since: 4.0

###### gtk_selection_model_unselect_range

Requests to unselect a range of items in the model.

since: 4.0

#### Signals

###### Gtk.SelectionModel::selection-changed

Emitted when the selection state of some of the items in `model` changes.

since: 4.0

#### Interface structure

    struct GtkSelectionModelInterface {
      gboolean (* is_selected) (
        GtkSelectionModel* model,
        guint position
      );
      GtkBitset* (* get_selection_in_range) (
        GtkSelectionModel* model,
        guint position,
        guint n_items
      );
      gboolean (* select_item) (
        GtkSelectionModel* model,
        guint position,
        gboolean unselect_rest
      );
      gboolean (* unselect_item) (
        GtkSelectionModel* model,
        guint position
      );
      gboolean (* select_range) (
        GtkSelectionModel* model,
        guint position,
        guint n_items,
        gboolean unselect_rest
      );
      gboolean (* unselect_range) (
        GtkSelectionModel* model,
        guint position,
        guint n_items
      );
      gboolean (* select_all) (
        GtkSelectionModel* model
      );
      gboolean (* unselect_all) (
        GtkSelectionModel* model
      );
      gboolean (* set_selection) (
        GtkSelectionModel* model,
        GtkBitset* selected,
        GtkBitset* mask
      );

    }

The list of virtual functions for the `GtkSelectionModel` interface. No function must be implemented, but unless `GtkSelectionModel::is_selected()` is implemented, it will not be possible to select items in the set.

The model does not need to implement any functions to support either selecting or unselecting items. Of course, if the model does not do that, it means that users cannot select or unselect items in a list widget using the model.

All selection functions fall back to `GtkSelectionModel::set_selection()` so it is sufficient to implement just that function for full selection support.

###### Interface members

`is_selected` |
    gboolean (* is_selected) (
        GtkSelectionModel* model,
        guint position
      )
| Return if the item at the given position is selected.
`get_selection_in_range` |
    GtkBitset* (* get_selection_in_range) (
        GtkSelectionModel* model,
        guint position,
        guint n_items
      )
| Return a bitset with all currently selected items in the given range. By default, this function will call `GtkSelectionModel::is_selected()` on all items in the given range.
`select_item` |
    gboolean (* select_item) (
        GtkSelectionModel* model,
        guint position,
        gboolean unselect_rest
      )
| Select the item in the given position. If the operation is known to fail, return `FALSE`.
`unselect_item` |
    gboolean (* unselect_item) (
        GtkSelectionModel* model,
        guint position
      )
| Unselect the item in the given position. If the operation is known to fail, return `FALSE`.
`select_range` |
    gboolean (* select_range) (
        GtkSelectionModel* model,
        guint position,
        guint n_items,
        gboolean unselect_rest
      )
| Select all items in the given range. If the operation is unsupported or known to fail for all items, return `FALSE`.
`unselect_range` |
    gboolean (* unselect_range) (
        GtkSelectionModel* model,
        guint position,
        guint n_items
      )
| Unselect all items in the given range. If the operation is unsupported or known to fail for all items, return `FALSE`.
`select_all` |
    gboolean (* select_all) (
        GtkSelectionModel* model
      )
| Select all items in the model. If the operation is unsupported or known to fail for all items, return `FALSE`.
`unselect_all` |
    gboolean (* unselect_all) (
        GtkSelectionModel* model
      )
| Unselect all items in the model. If the operation is unsupported or known to fail for all items, return `FALSE`.
`set_selection` |
    gboolean (* set_selection) (
        GtkSelectionModel* model,
        GtkBitset* selected,
        GtkBitset* mask
      )
| Set selection state of all items in mask to selected. See `gtk_selection_model_set_selection()` for a detailed explanation of this function.

#### Virtual methods

###### Gtk.SelectionModel.get_selection_in_range

Gets the set of selected items in a range.

since: 4.0

###### Gtk.SelectionModel.is_selected

Checks if the given item is selected.

since: 4.0

###### Gtk.SelectionModel.select_all

Requests to select all items in the model.

since: 4.0

###### Gtk.SelectionModel.select_item

Requests to select an item in the model.

since: 4.0

###### Gtk.SelectionModel.select_range

Requests to select a range of items in the model.

since: 4.0

###### Gtk.SelectionModel.set_selection

Make selection changes.

since: 4.0

###### Gtk.SelectionModel.unselect_all

Requests to unselect all items in the model.

since: 4.0

###### Gtk.SelectionModel.unselect_item

Requests to unselect an item in the model.

since: 4.0

###### Gtk.SelectionModel.unselect_range

Requests to unselect a range of items in the model.

since: 4.0