Module javafx.controls
Package javafx.scene.control

# Class SelectionModel<T>

java.lang.Object
javafx.scene.control.SelectionModel<T>

Type Parameters:
  `T` - The type of the item contained in the control that can be selected.

Direct Known Subclasses:
  `MultipleSelectionModel`, `SingleSelectionModel`

public abstract class SelectionModel<T> extends Object
SelectionModel is an abstract class used by UI controls to provide a consistent API for maintaining selection.

Since:
  JavaFX 2.0

- ## Property Summary

  Properties
  Type
  Property
  Description
  `final ReadOnlyIntegerProperty`
  `selectedIndex`
  Refers to the selected index property, which is used to indicate the currently selected index value in the selection model.
  `final ReadOnlyObjectProperty<T>`
  `selectedItem`
  Refers to the selected item property, which is used to indicate the currently selected item in the selection model.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SelectionModel()`
  Creates a default SelectionModel instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract void`
  `clearAndSelect(int index)`
  A method that clears any selection prior to setting the selection to the given index.
  `abstract void`
  `clearSelection()`
  Clears the selection model of all selected indices.
  `abstract void`
  `clearSelection(int index)`
  This method will clear the selection of the item in the given index.
  `final int`
  `getSelectedIndex()`
  Returns the integer value indicating the currently selected index in this model.
  `final T`
  `getSelectedItem()`
  Returns the currently selected object (which resides in the selected index position).
  `abstract boolean`
  `isEmpty()`
  This method is available to test whether there are any selected indices/items.
  `abstract boolean`
  `isSelected(int index)`
  Convenience method to inform if the given index is currently selected in this SelectionModel.
  `abstract void`
  `select(int index)`
  This will select the given index in the selection model, assuming the index is within the valid range (i.e.
  `abstract void`
  `select(T obj)`
  This method will attempt to select the index that contains the given object.
  `final ReadOnlyIntegerProperty`
  `selectedIndexProperty()`
  Refers to the selected index property, which is used to indicate the currently selected index value in the selection model.
  `final ReadOnlyObjectProperty<T>`
  `selectedItemProperty()`
  Refers to the selected item property, which is used to indicate the currently selected item in the selection model.
  `abstract void`
  `selectFirst()`
  This method will attempt to select the first index in the control.
  `abstract void`
  `selectLast()`
  This method will attempt to select the last index in the control.
  `abstract void`
  `selectNext()`
  This method will attempt to select the index directly after the current focused index.
  `abstract void`
  `selectPrevious()`
  This method will attempt to select the index directly before the current focused index.
  `protected final void`
  `setSelectedIndex(int value)`
  Sets the value of the `selectedIndex` property.
  `protected final void`
  `setSelectedItem(T value)`
  Sets the value of the `selectedItem` property.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Property Details

  - ### selectedIndex

    public final ReadOnlyIntegerProperty selectedIndexProperty

    Refers to the selected index property, which is used to indicate the currently selected index value in the selection model. The selected index is either -1, to represent that there is no selection, or an integer value that is within the range of the underlying data model size.

    The selected index property is most commonly used when the selection model only allows single selection, but is equally applicable when in multiple selection mode. When in this mode, the selected index will always represent the last selection made.

    Note that in the case of multiple selection, it is possible to add a `ListChangeListener` to the collection returned by `MultipleSelectionModel.getSelectedIndices()` to be informed whenever the selection changes, and this will also work in the case of single selection.

    See Also:
      - `getSelectedIndex()`
      - `setSelectedIndex(int)`
      - `selectedIndexProperty()`

  - ### selectedItem

    public final ReadOnlyObjectProperty<T> selectedItemProperty

    Refers to the selected item property, which is used to indicate the currently selected item in the selection model. The selected item is either null, to represent that there is no selection, or an Object that is retrieved from the underlying data model of the control the selection model is associated with.

    The selected item property is most commonly used when the selection model is set to be single selection, but is equally applicable when in multiple selection mode. When in this mode, the selected item will always represent the last selection made.

    See Also:
      - `getSelectedItem()`
      - `setSelectedItem(T)`
      - `selectedItemProperty()`

- ## Constructor Details

  - ### SelectionModel

    public SelectionModel()
    Creates a default SelectionModel instance.

- ## Method Details

  - ### selectedIndexProperty

    public final ReadOnlyIntegerProperty selectedIndexProperty()

    Refers to the selected index property, which is used to indicate the currently selected index value in the selection model. The selected index is either -1, to represent that there is no selection, or an integer value that is within the range of the underlying data model size.

    The selected index property is most commonly used when the selection model only allows single selection, but is equally applicable when in multiple selection mode. When in this mode, the selected index will always represent the last selection made.

    Note that in the case of multiple selection, it is possible to add a `ListChangeListener` to the collection returned by `MultipleSelectionModel.getSelectedIndices()` to be informed whenever the selection changes, and this will also work in the case of single selection.

    Returns:
      the selected index property
    See Also:
      - `getSelectedIndex()`
      - `setSelectedIndex(int)`

  - ### setSelectedIndex

    protected final void setSelectedIndex(int value)
    Sets the value of the `selectedIndex` property.
    Property description:

      Refers to the selected index property, which is used to indicate the currently selected index value in the selection model. The selected index is either -1, to represent that there is no selection, or an integer value that is within the range of the underlying data model size.

      The selected index property is most commonly used when the selection model only allows single selection, but is equally applicable when in multiple selection mode. When in this mode, the selected index will always represent the last selection made.

      Note that in the case of multiple selection, it is possible to add a `ListChangeListener` to the collection returned by `MultipleSelectionModel.getSelectedIndices()` to be informed whenever the selection changes, and this will also work in the case of single selection.

    Parameters:
      `value` - the value for the `selectedIndex` property
    See Also:
      - `getSelectedIndex()`
      - `selectedIndexProperty()`

  - ### getSelectedIndex

    public final int getSelectedIndex()

    Returns the integer value indicating the currently selected index in this model. If there are multiple items selected, this will return the most recent selection made.

    Note that the returned value is a snapshot in time - if you wish to observe the selection model for changes to the selected index, you can add a ChangeListener as such:

         SelectionModel sm = ...;
         InvalidationListener listener = ...;
         sm.selectedIndexProperty().addListener(listener);

    Returns:
      the selected index

  - ### selectedItemProperty

    public final ReadOnlyObjectProperty<T> selectedItemProperty()

    Refers to the selected item property, which is used to indicate the currently selected item in the selection model. The selected item is either null, to represent that there is no selection, or an Object that is retrieved from the underlying data model of the control the selection model is associated with.

    The selected item property is most commonly used when the selection model is set to be single selection, but is equally applicable when in multiple selection mode. When in this mode, the selected item will always represent the last selection made.

    Returns:
      the selected item property
    See Also:
      - `getSelectedItem()`
      - `setSelectedItem(T)`

  - ### setSelectedItem

    protected final void setSelectedItem(T value)
    Sets the value of the `selectedItem` property.
    Property description:

      Refers to the selected item property, which is used to indicate the currently selected item in the selection model. The selected item is either null, to represent that there is no selection, or an Object that is retrieved from the underlying data model of the control the selection model is associated with.

      The selected item property is most commonly used when the selection model is set to be single selection, but is equally applicable when in multiple selection mode. When in this mode, the selected item will always represent the last selection made.

    Parameters:
      `value` - the value for the `selectedItem` property
    See Also:
      - `getSelectedItem()`
      - `selectedItemProperty()`

  - ### getSelectedItem

    public final T getSelectedItem()
    Returns the currently selected object (which resides in the selected index position). If there are multiple items selected, this will return the object contained at the index returned by getSelectedIndex() (which is always the index to the most recently selected item).

    Note that the returned value is a snapshot in time - if you wish to observe the selection model for changes to the selected item, you can add a ChangeListener as such:

         SelectionModel sm = ...;
         InvalidationListener listener = ...;
         sm.selectedItemProperty().addListener(listener);

    Returns:
      the selected item

  - ### clearAndSelect

    public abstract void clearAndSelect(int index)
    A method that clears any selection prior to setting the selection to the given index. The purpose of this method is to avoid having to call `clearSelection()` first, meaning that observers that are listening to the `selected index` property will not see the selected index being temporarily set to -1.
    Parameters:
      `index` - The index that should be the only selected index in this selection model.

  - ### select

    public abstract void select(int index)

    This will select the given index in the selection model, assuming the index is within the valid range (i.e. greater than or equal to zero, and less than the total number of items in the underlying data model).

    If there is already one or more indices selected in this model, calling this method will not clear these selections - to do so it is necessary to first call `clearSelection()`.

    If the index is already selected, it will not be selected again, or unselected. However, if multiple selection is implemented, then calling select on an already selected index will have the effect of making the index the new selected index (as returned by `getSelectedIndex()`.

    Parameters:
      `index` - The position of the item to select in the selection model.

  - ### select

    public abstract void select(T obj)

    This method will attempt to select the index that contains the given object. It will iterate through the underlying data model until it finds an item whose value is equal to the given object. At this point it will stop iterating - this means that this method will not select multiple indices.

    Parameters:
      `obj` - The object to attempt to select in the underlying data model.

  - ### clearSelection

    public abstract void clearSelection(int index)

    This method will clear the selection of the item in the given index. If the given index is not selected, nothing will happen.

    Parameters:
      `index` - The selected item to deselect.

  - ### clearSelection

    public abstract void clearSelection()

    Clears the selection model of all selected indices.

  - ### isSelected

    public abstract boolean isSelected(int index)

    Convenience method to inform if the given index is currently selected in this SelectionModel. Is functionally equivalent to calling `getSelectedIndices().contains(index)`.

    Parameters:
      `index` - The index to check as to whether it is currently selected or not.
    Returns:
      True if the given index is selected, false otherwise.

  - ### isEmpty

    public abstract boolean isEmpty()
    This method is available to test whether there are any selected indices/items. It will return true if there are no selected items, and false if there are.
    Returns:
      Will return true if there are no selected items, and false if there are.

  - ### selectPrevious

    public abstract void selectPrevious()

    This method will attempt to select the index directly before the current focused index. If clearSelection is not called first, this method will have the result of selecting the previous index, whilst retaining the selection of any other currently selected indices.

    Calling this method will only succeed if:

    - There is currently a lead/focused index.
    - The lead/focus index is not the first index in the control.
    - The previous index is not already selected.

    If any of these conditions is false, no selection event will take place.

  - ### selectNext

    public abstract void selectNext()

    This method will attempt to select the index directly after the current focused index. If clearSelection is not called first, this method will have the result of selecting the next index, whilst retaining the selection of any other currently selected indices.

    Calling this method will only succeed if:

    - There is currently a lead/focused index.
    - The lead/focus index is not the last index in the control.
    - The next index is not already selected.

    If any of these conditions is false, no selection event will take place.

  - ### selectFirst

    public abstract void selectFirst()

    This method will attempt to select the first index in the control. If clearSelection is not called first, this method will have the result of selecting the first index, whilst retaining the selection of any other currently selected indices.

    If the first index is already selected, calling this method will have no result, and no selection event will take place.

  - ### selectLast

    public abstract void selectLast()

    This method will attempt to select the last index in the control. If clearSelection is not called first, this method will have the result of selecting the last index, whilst retaining the selection of any other currently selected indices.

    If the last index is already selected, calling this method will have no result, and no selection event will take place.