Back to index...

	/*
	* Copyright (c) 1997, 2006, 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 javax.swing;

	import javax.swing.event.*;

	/**
	* This interface represents the current state of the
	* selection for any of the components that display a
	* list of values with stable indices. The selection is
	* modeled as a set of intervals, each interval represents
	* a contiguous range of selected list elements.
	* The methods for modifying the set of selected intervals
	* all take a pair of indices, index0 and index1, that represent
	* a closed interval, i.e. the interval includes both index0 and
	* index1.
	*
	* @author Hans Muller
	* @author Philip Milne
	* @see DefaultListSelectionModel
	*/

	public interface ListSelectionModel
	{
	/**
	* A value for the selectionMode property: select one list index
	* at a time.
	*
	* @see #setSelectionMode
	*/
	int SINGLE_SELECTION = 0;

	/**
	* A value for the selectionMode property: select one contiguous
	* range of indices at a time.
	*
	* @see #setSelectionMode
	*/
	int SINGLE_INTERVAL_SELECTION = 1;

	/**
	* A value for the selectionMode property: select one or more
	* contiguous ranges of indices at a time.
	*
	* @see #setSelectionMode
	*/
	int MULTIPLE_INTERVAL_SELECTION = 2;


	/**
	* Changes the selection to be between {@code index0} and {@code index1}
	* inclusive. {@code index0} doesn't have to be less than or equal to
	* {@code index1}.
	* <p>
	* In {@code SINGLE_SELECTION} selection mode, only the second index
	* is used.
	* <p>
	* If this represents a change to the current selection, then each
	* {@code ListSelectionListener} is notified of the change.
	*
	* @param index0 one end of the interval.
	* @param index1 other end of the interval
	* @see #addListSelectionListener
	*/
	void setSelectionInterval(int index0, int index1);


	/**
	* Changes the selection to be the set union of the current selection
	* and the indices between {@code index0} and {@code index1} inclusive.
	* {@code index0} doesn't have to be less than or equal to {@code index1}.
	* <p>
	* In {@code SINGLE_SELECTION} selection mode, this is equivalent
	* to calling {@code setSelectionInterval}, and only the second index
	* is used. In {@code SINGLE_INTERVAL_SELECTION} selection mode, this
	* method behaves like {@code setSelectionInterval}, unless the given
	* interval is immediately adjacent to or overlaps the existing selection,
	* and can therefore be used to grow the selection.
	* <p>
	* If this represents a change to the current selection, then each
	* {@code ListSelectionListener} is notified of the change.
	*
	* @param index0 one end of the interval.
	* @param index1 other end of the interval
	* @see #addListSelectionListener
	* @see #setSelectionInterval
	*/
	void addSelectionInterval(int index0, int index1);


	/**
	* Changes the selection to be the set difference of the current selection
	* and the indices between {@code index0} and {@code index1} inclusive.
	* {@code index0} doesn't have to be less than or equal to {@code index1}.
	* <p>
	* In {@code SINGLE_INTERVAL_SELECTION} selection mode, if the removal
	* would produce two disjoint selections, the removal is extended through
	* the greater end of the selection. For example, if the selection is
	* {@code 0-10} and you supply indices {@code 5,6} (in any order) the
	* resulting selection is {@code 0-4}.
	* <p>
	* If this represents a change to the current selection, then each
	* {@code ListSelectionListener} is notified of the change.
	*
	* @param index0 one end of the interval.
	* @param index1 other end of the interval
	* @see #addListSelectionListener
	*/
	void removeSelectionInterval(int index0, int index1);


	/**
	* Returns the first selected index or -1 if the selection is empty.
	*/
	int getMinSelectionIndex();


	/**
	* Returns the last selected index or -1 if the selection is empty.
	*/
	int getMaxSelectionIndex();


	/**
	* Returns true if the specified index is selected.
	*/
	boolean isSelectedIndex(int index);


	/**
	* Return the first index argument from the most recent call to
	* setSelectionInterval(), addSelectionInterval() or removeSelectionInterval().
	* The most recent index0 is considered the "anchor" and the most recent
	* index1 is considered the "lead". Some interfaces display these
	* indices specially, e.g. Windows95 displays the lead index with a
	* dotted yellow outline.
	*
	* @see #getLeadSelectionIndex
	* @see #setSelectionInterval
	* @see #addSelectionInterval
	*/
	int getAnchorSelectionIndex();


	/**
	* Set the anchor selection index.
	*
	* @see #getAnchorSelectionIndex
	*/
	void setAnchorSelectionIndex(int index);


	/**
	* Return the second index argument from the most recent call to
	* setSelectionInterval(), addSelectionInterval() or removeSelectionInterval().
	*
	* @see #getAnchorSelectionIndex
	* @see #setSelectionInterval
	* @see #addSelectionInterval
	*/
	int getLeadSelectionIndex();

	/**
	* Set the lead selection index.
	*
	* @see #getLeadSelectionIndex
	*/
	void setLeadSelectionIndex(int index);

	/**
	* Change the selection to the empty set. If this represents
	* a change to the current selection then notify each ListSelectionListener.
	*
	* @see #addListSelectionListener
	*/
	void clearSelection();

	/**
	* Returns true if no indices are selected.
	*/
	boolean isSelectionEmpty();

	/**
	* Insert length indices beginning before/after index. This is typically
	* called to sync the selection model with a corresponding change
	* in the data model.
	*/
	void insertIndexInterval(int index, int length, boolean before);

	/**
	* Remove the indices in the interval index0,index1 (inclusive) from
	* the selection model. This is typically called to sync the selection
	* model width a corresponding change in the data model.
	*/
	void removeIndexInterval(int index0, int index1);

	/**
	* Sets the {@code valueIsAdjusting} property, which indicates whether
	* or not upcoming selection changes should be considered part of a single
	* change. The value of this property is used to initialize the
	* {@code valueIsAdjusting} property of the {@code ListSelectionEvent}s that
	* are generated.
	* <p>
	* For example, if the selection is being updated in response to a user
	* drag, this property can be set to {@code true} when the drag is initiated
	* and set to {@code false} when the drag is finished. During the drag,
	* listeners receive events with a {@code valueIsAdjusting} property
	* set to {@code true}. At the end of the drag, when the change is
	* finalized, listeners receive an event with the value set to {@code false}.
	* Listeners can use this pattern if they wish to update only when a change
	* has been finalized.
	* <p>
	* Setting this property to {@code true} begins a series of changes that
	* is to be considered part of a single change. When the property is changed
	* back to {@code false}, an event is sent out characterizing the entire
	* selection change (if there was one), with the event's
	* {@code valueIsAdjusting} property set to {@code false}.
	*
	* @param valueIsAdjusting the new value of the property
	* @see #getValueIsAdjusting
	* @see javax.swing.event.ListSelectionEvent#getValueIsAdjusting
	*/
	void setValueIsAdjusting(boolean valueIsAdjusting);

	/**
	* Returns {@code true} if the selection is undergoing a series of changes.
	*
	* @return true if the selection is undergoing a series of changes
	* @see #setValueIsAdjusting
	*/
	boolean getValueIsAdjusting();

	/**
	* Sets the selection mode. The following list describes the accepted
	* selection modes:
	* <ul>
	* <li>{@code ListSelectionModel.SINGLE_SELECTION} -
	* Only one list index can be selected at a time. In this mode,
	* {@code setSelectionInterval} and {@code addSelectionInterval} are
	* equivalent, both replacing the current selection with the index
	* represented by the second argument (the "lead").
	* <li>{@code ListSelectionModel.SINGLE_INTERVAL_SELECTION} -
	* Only one contiguous interval can be selected at a time.
	* In this mode, {@code addSelectionInterval} behaves like
	* {@code setSelectionInterval} (replacing the current selection),
	* unless the given interval is immediately adjacent to or overlaps
	* the existing selection, and can therefore be used to grow it.
	* <li>{@code ListSelectionModel.MULTIPLE_INTERVAL_SELECTION} -
	* In this mode, there's no restriction on what can be selected.
	* </ul>
	*
	* @see #getSelectionMode
	* @throws IllegalArgumentException if the selection mode isn't
	* one of those allowed
	*/
	void setSelectionMode(int selectionMode);

	/**
	* Returns the current selection mode.
	*
	* @return the current selection mode
	* @see #setSelectionMode
	*/
	int getSelectionMode();

	/**
	* Add a listener to the list that's notified each time a change
	* to the selection occurs.
	*
	* @param x the ListSelectionListener
	* @see #removeListSelectionListener
	* @see #setSelectionInterval
	* @see #addSelectionInterval
	* @see #removeSelectionInterval
	* @see #clearSelection
	* @see #insertIndexInterval
	* @see #removeIndexInterval
	*/
	void addListSelectionListener(ListSelectionListener x);

	/**
	* Remove a listener from the list that's notified each time a
	* change to the selection occurs.
	*
	* @param x the ListSelectionListener
	* @see #addListSelectionListener
	*/
	void removeListSelectionListener(ListSelectionListener x);
	}

Back to index...