http://openjdk.java.net/projects/openjfx/javafx-controls/: OpenJFX JavaFX
  • OpenJFX Mailing List 
/*
 * Copyright (c) 2010, 2017, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javafx.scene.control;

import javafx.beans.property.ReadOnlyIntegerProperty;
import javafx.beans.property.ReadOnlyIntegerWrapper;
import javafx.beans.property.ReadOnlyObjectProperty;
import javafx.beans.property.ReadOnlyObjectWrapper;
import javafx.collections.ListChangeListener;


SelectionModel is an abstract class used by UI controls to provide a
consistent API for maintaining selection.

Type parameters:
  • <T> – The type of the item contained in the control that can be selected.
Since:JavaFX 2.0
/**
 * SelectionModel is an abstract class used by UI controls to provide a
 * consistent API for maintaining selection.
 *
 * @param <T> The type of the item contained in the control that can be selected.
 * @since JavaFX 2.0
 */
public abstract class SelectionModel<T> {

    /***************************************************************************
     *                                                                         *
     * Selection Properties                                                    *
     *                                                                         *
     **************************************************************************/

    
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
/**
     * <p>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.
     *
     * <p>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.
     *
     * <p>Note that in the case of multiple selection, it is possible to add
     * a {@link ListChangeListener} to the collection returned by
     * {@link MultipleSelectionModel#getSelectedIndices()} to be informed whenever
     * the selection changes, and this will also work in the case of single selection.
     * @return the selected index property
     */
    public final ReadOnlyIntegerProperty selectedIndexProperty() { return selectedIndex.getReadOnlyProperty(); }
    private ReadOnlyIntegerWrapper selectedIndex = new ReadOnlyIntegerWrapper(this, "selectedIndex", -1);
    protected final void setSelectedIndex(int value) { selectedIndex.set(value); }

    
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
/**
     * <p>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.
     *
     * <p>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:
     *
     * <pre><code>
     * SelectionModel sm = ...;
     * InvalidationListener listener = ...;
     * sm.selectedIndexProperty().addListener(listener);
     * </code></pre>
     * @return the selected index
     */
    public final int getSelectedIndex() { return selectedIndexProperty().get(); }

    
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
/**
     * <p>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.
     *
     * <p>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.
     * @return the selected item property
     */
    public final ReadOnlyObjectProperty<T> selectedItemProperty() { return selectedItem.getReadOnlyProperty(); }
    private ReadOnlyObjectWrapper<T> selectedItem = new ReadOnlyObjectWrapper<T>(this, "selectedItem");
    protected final void setSelectedItem(T value) { selectedItem.set(value); }

    
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
/**
     * 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).
     *
     * <p>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:
     *
     * <pre><code>
     * SelectionModel sm = ...;
     * InvalidationListener listener = ...;
     * sm.selectedItemProperty().addListener(listener);
     * </code></pre>
     * @return the selected item
     */
    public final T getSelectedItem() { return selectedItemProperty().get(); }


    /***************************************************************************
     *                                                                         *
     * Constructor                                                             *
     *                                                                         *
     **************************************************************************/

    
Creates a default SelectionModel instance.

/**
     * Creates a default SelectionModel instance.
     */
    public SelectionModel() { }


    /***************************************************************************
     *                                                                         *
     * Selection API                                                           *
     *                                                                         *
     **************************************************************************/


    
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. 
Params:
  • index – The index that should be the only selected index in this
     selection model.
/**
     * 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
     * {@link #clearSelection()} first, meaning that observers that are listening to
     * the {@link #selectedIndexProperty() selected index} property will not
     * see the selected index being temporarily set to -1.
     *
     * @param index The index that should be the only selected index in this
     *      selection model.
     */
    public abstract void clearAndSelect(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(). 
Params:
  • index – The position of the item to select in the selection model.
/**
     * <p>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).
     *
     * <p>If there is already one or more indices selected in this model, calling
     * this method will <b>not</b> clear these selections - to do so it is
     * necessary to first call {@link #clearSelection()}.
     *
     * <p>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 {@link #getSelectedIndex()}.
     *
     * @param index The position of the item to select in the selection model.
     */
    public abstract void select(int index);

    
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.

Params:
  • obj – The object to attempt to select in the underlying data model.
/**
     * <p>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.
     *
     * @param obj The object to attempt to select in the underlying data model.
     */
    public abstract void select(T obj);

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

Params:
  • index – The selected item to deselect.
/**
     * <p>This method will clear the selection of the item in the given index.
     * If the given index is not selected, nothing will happen.
     *
     * @param index The selected item to deselect.
     */
    public abstract void clearSelection(int index);

    
Clears the selection model of all selected indices.

/**
     * <p>Clears the selection model of all selected indices.
     */
    public abstract void clearSelection();

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

Params:
  • index – The index to check as to whether it is currently selected
     or not.
Returns:True if the given index is selected, false otherwise.
/**
     * <p>Convenience method to inform if the given index is currently selected
     * in this SelectionModel. Is functionally equivalent to calling
     * <code>getSelectedIndices().contains(index)</code>.
     *
     * @param index The index to check as to whether it is currently selected
     *      or not.
     * @return True if the given index is selected, false otherwise.
     */
    public abstract boolean isSelected(int index);

    
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.
/**
     * This method is available to test whether there are any selected
     * indices/items. It will return true if there are <b>no</b> selected items,
     * and false if there are.
     *
     * @return Will return true if there are <b>no</b> selected items, and false
     *          if there are.
     */
    public abstract boolean isEmpty();

    
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.


/**
     * <p>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.</p>
     *
     * <p>Calling this method will only succeed if:</p>
     *
     * <ul>
     *   <li>There is currently a lead/focused index.
     *   <li>The lead/focus index is not the first index in the control.
     *   <li>The previous index is not already selected.
     * </ul>
     *
     * <p>If any of these conditions is false, no selection event will take
     * place.</p>
     */
    public abstract void selectPrevious();

    
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.


/**
     * <p>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.</p>
     *
     * <p>Calling this method will only succeed if:</p>
     *
     * <ul>
     *   <li>There is currently a lead/focused index.
     *   <li>The lead/focus index is not the last index in the control.
     *   <li>The next index is not already selected.
     * </ul>
     *
     * <p>If any of these conditions is false, no selection event will take
     * place.</p>
     */
    public abstract void selectNext();

    
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.


/**
     * <p>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.</p>
     *
     * <p>If the first index is already selected, calling this method will have
     * no result, and no selection event will take place.</p>
     */
    public abstract void selectFirst();

    
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.


/**
     * <p>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.</p>
     *
     * <p>If the last index is already selected, calling this method will have
     * no result, and no selection event will take place.</p>
     */
    public abstract void selectLast();
}