< prev index next >
src/java.desktop/share/classes/java/awt/List.java
Print this page
*** 34,44 ****
import java.io.IOException;
import javax.accessibility.*;
/**
! * The <code>List</code> component presents the user with a
* scrolling list of text items. The list can be set up so that
* the user can choose either one item or multiple items.
* <p>
* For example, the code . . .
*
--- 34,44 ----
import java.io.IOException;
import javax.accessibility.*;
/**
! * The {@code List} component presents the user with a
* scrolling list of text items. The list can be set up so that
* the user can choose either one item or multiple items.
* <p>
* For example, the code . . .
*
*** 55,100 ****
* lst.add("Neptune");
* lst.add("Pluto");
* cnt.add(lst);
* </pre></blockquote><hr>
* <p>
! * where <code>cnt</code> is a container, produces the following
* scrolling list:
* <p>
* <img src="doc-files/List-1.gif"
* alt="Shows a list containing: Venus, Earth, JavaSoft, and Mars. Javasoft is selected." style="float:center; margin: 7px 10px;">
* <p>
* If the List allows multiple selections, then clicking on
* an item that is already selected deselects it. In the preceding
* example, only one item from the scrolling list can be selected
* at a time, since the second argument when creating the new scrolling
! * list is <code>false</code>. If the List does not allow multiple
* selections, selecting an item causes any other selected item
* to be deselected.
* <p>
* Note that the list in the example shown was created with four visible
* rows. Once the list has been created, the number of visible rows
! * cannot be changed. A default <code>List</code> is created with
! * four rows, so that <code>lst = new List()</code> is equivalent to
! * <code>list = new List(4, false)</code>.
* <p>
* Beginning with Java 1.1, the Abstract Window Toolkit
! * sends the <code>List</code> object all mouse, keyboard, and focus events
* that occur over it. (The old AWT event model is being maintained
* only for backwards compatibility, and its use is discouraged.)
* <p>
* When an item is selected or deselected by the user, AWT sends an instance
! * of <code>ItemEvent</code> to the list.
* When the user double-clicks on an item in a scrolling list,
! * AWT sends an instance of <code>ActionEvent</code> to the
* list following the item event. AWT also generates an action event
* when the user presses the return key while an item in the
* list is selected.
* <p>
* If an application wants to perform some action based on an item
* in this list being selected or activated by the user, it should implement
! * <code>ItemListener</code> or <code>ActionListener</code>
* as appropriate and register the new listener to receive
* events from this list.
* <p>
* For multiple-selection scrolling lists, it is considered a better
* user interface to use an external gesture (such as clicking on a
--- 55,100 ----
* lst.add("Neptune");
* lst.add("Pluto");
* cnt.add(lst);
* </pre></blockquote><hr>
* <p>
! * where {@code cnt} is a container, produces the following
* scrolling list:
* <p>
* <img src="doc-files/List-1.gif"
* alt="Shows a list containing: Venus, Earth, JavaSoft, and Mars. Javasoft is selected." style="float:center; margin: 7px 10px;">
* <p>
* If the List allows multiple selections, then clicking on
* an item that is already selected deselects it. In the preceding
* example, only one item from the scrolling list can be selected
* at a time, since the second argument when creating the new scrolling
! * list is {@code false}. If the List does not allow multiple
* selections, selecting an item causes any other selected item
* to be deselected.
* <p>
* Note that the list in the example shown was created with four visible
* rows. Once the list has been created, the number of visible rows
! * cannot be changed. A default {@code List} is created with
! * four rows, so that {@code lst = new List()} is equivalent to
! * {@code list = new List(4, false)}.
* <p>
* Beginning with Java 1.1, the Abstract Window Toolkit
! * sends the {@code List} object all mouse, keyboard, and focus events
* that occur over it. (The old AWT event model is being maintained
* only for backwards compatibility, and its use is discouraged.)
* <p>
* When an item is selected or deselected by the user, AWT sends an instance
! * of {@code ItemEvent} to the list.
* When the user double-clicks on an item in a scrolling list,
! * AWT sends an instance of {@code ActionEvent} to the
* list following the item event. AWT also generates an action event
* when the user presses the return key while an item in the
* list is selected.
* <p>
* If an application wants to perform some action based on an item
* in this list being selected or activated by the user, it should implement
! * {@code ItemListener} or {@code ActionListener}
* as appropriate and register the new listener to receive
* events from this list.
* <p>
* For multiple-selection scrolling lists, it is considered a better
* user interface to use an external gesture (such as clicking on a
*** 117,141 ****
*/
Vector<String> items = new Vector<>();
/**
* This field will represent the number of visible rows in the
! * <code>List</code> Component. It is specified only once, and
* that is when the list component is actually
* created. It will never change.
*
* @serial
* @see #getRows()
*/
int rows = 0;
/**
! * <code>multipleMode</code> is a variable that will
! * be set to <code>true</code> if a list component is to be set to
* multiple selection mode, that is where the user can
* select more than one item in a list at one time.
! * <code>multipleMode</code> will be set to false if the
* list component is set to single selection, that is where
* the user can only select one item on the list at any
* one time.
*
* @serial
--- 117,141 ----
*/
Vector<String> items = new Vector<>();
/**
* This field will represent the number of visible rows in the
! * {@code List} Component. It is specified only once, and
* that is when the list component is actually
* created. It will never change.
*
* @serial
* @see #getRows()
*/
int rows = 0;
/**
! * {@code multipleMode} is a variable that will
! * be set to {@code true} if a list component is to be set to
* multiple selection mode, that is where the user can
* select more than one item in a list at one time.
! * {@code multipleMode} will be set to false if the
* list component is set to single selection, that is where
* the user can only select one item on the list at any
* one time.
*
* @serial
*** 143,153 ****
* @see #setMultipleMode(boolean)
*/
boolean multipleMode = false;
/**
! * <code>selected</code> is an array that will contain
* the indices of items that have been selected.
*
* @serial
* @see #getSelectedIndexes()
* @see #getSelectedIndex()
--- 143,153 ----
* @see #setMultipleMode(boolean)
*/
boolean multipleMode = false;
/**
! * {@code selected} is an array that will contain
* the indices of items that have been selected.
*
* @serial
* @see #getSelectedIndexes()
* @see #getSelectedIndex()
*** 176,186 ****
/**
* Creates a new scrolling list.
* By default, there are four visible lines and multiple selections are
* not allowed. Note that this is a convenience method for
! * <code>List(0, false)</code>. Also note that the number of visible
* lines in the list cannot be changed after it has been created.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true.
* @see java.awt.GraphicsEnvironment#isHeadless
*/
--- 176,186 ----
/**
* Creates a new scrolling list.
* By default, there are four visible lines and multiple selections are
* not allowed. Note that this is a convenience method for
! * {@code List(0, false)}. Also note that the number of visible
* lines in the list cannot be changed after it has been created.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true.
* @see java.awt.GraphicsEnvironment#isHeadless
*/
*** 190,200 ****
/**
* Creates a new scrolling list initialized with the specified
* number of visible lines. By default, multiple selections are
* not allowed. Note that this is a convenience method for
! * <code>List(rows, false)</code>. Also note that the number
* of visible rows in the list cannot be changed after it has
* been created.
* @param rows the number of items to show.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true.
--- 190,200 ----
/**
* Creates a new scrolling list initialized with the specified
* number of visible lines. By default, multiple selections are
* not allowed. Note that this is a convenience method for
! * {@code List(rows, false)}. Also note that the number
* of visible rows in the list cannot be changed after it has
* been created.
* @param rows the number of items to show.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true.
*** 215,230 ****
* Creates a new scrolling list initialized to display the specified
* number of rows. Note that if zero rows are specified, then
* the list will be created with a default of four rows.
* Also note that the number of visible rows in the list cannot
* be changed after it has been created.
! * If the value of <code>multipleMode</code> is
! * <code>true</code>, then the user can select multiple items from
! * the list. If it is <code>false</code>, only one item at a time
* can be selected.
* @param rows the number of items to show.
! * @param multipleMode if <code>true</code>,
* then multiple selections are allowed;
* otherwise, only one item can be selected at a time.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true.
* @see java.awt.GraphicsEnvironment#isHeadless
--- 215,230 ----
* Creates a new scrolling list initialized to display the specified
* number of rows. Note that if zero rows are specified, then
* the list will be created with a default of four rows.
* Also note that the number of visible rows in the list cannot
* be changed after it has been created.
! * If the value of {@code multipleMode} is
! * {@code true}, then the user can select multiple items from
! * the list. If it is {@code false}, only one item at a time
* can be selected.
* @param rows the number of items to show.
! * @param multipleMode if {@code true},
* then multiple selections are allowed;
* otherwise, only one item can be selected at a time.
* @exception HeadlessException if GraphicsEnvironment.isHeadless()
* returns true.
* @see java.awt.GraphicsEnvironment#isHeadless
*** 235,245 ****
this.multipleMode = multipleMode;
}
/**
* Construct a name for this component. Called by
! * <code>getName</code> when the name is <code>null</code>.
*/
String constructComponentName() {
synchronized (List.class) {
return base + nameCounter++;
}
--- 235,245 ----
this.multipleMode = multipleMode;
}
/**
* Construct a name for this component. Called by
! * {@code getName} when the name is {@code null}.
*/
String constructComponentName() {
synchronized (List.class) {
return base + nameCounter++;
}
*** 284,294 ****
/**
* Returns the number of items in the list.
*
* @return the number of items in the list
* @deprecated As of JDK version 1.1,
! * replaced by <code>getItemCount()</code>.
*/
@Deprecated
public int countItems() {
return items.size();
}
--- 284,294 ----
/**
* Returns the number of items in the list.
*
* @return the number of items in the list
* @deprecated As of JDK version 1.1,
! * replaced by {@code getItemCount()}.
*/
@Deprecated
public int countItems() {
return items.size();
}
*** 337,347 ****
/**
* Adds the specified item to the end of the list.
*
* @param item the item to be added
! * @deprecated replaced by <code>add(String)</code>.
*/
@Deprecated
public void addItem(String item) {
addItem(item, -1);
}
--- 337,347 ----
/**
* Adds the specified item to the end of the list.
*
* @param item the item to be added
! * @deprecated replaced by {@code add(String)}.
*/
@Deprecated
public void addItem(String item) {
addItem(item, -1);
}
*** 352,363 ****
* zero-based. If the value of the index is less than zero,
* or if the value of the index is greater than or equal to
* the number of items in the list, then the item is added
* to the end of the list.
* @param item the item to be added;
! * if this parameter is <code>null</code> then the item is
! * treated as an empty string, <code>""</code>
* @param index the position at which to add the item
* @since 1.1
*/
public void add(String item, int index) {
addItem(item, index);
--- 352,363 ----
* zero-based. If the value of the index is less than zero,
* or if the value of the index is greater than or equal to
* the number of items in the list, then the item is added
* to the end of the list.
* @param item the item to be added;
! * if this parameter is {@code null} then the item is
! * treated as an empty string, {@code ""}
* @param index the position at which to add the item
* @since 1.1
*/
public void add(String item, int index) {
addItem(item, index);
*** 367,377 ****
* Adds the specified item to the list
* at the position indicated by the index.
*
* @param item the item to be added
* @param index the position at which to add the item
! * @deprecated replaced by <code>add(String, int)</code>.
*/
@Deprecated
public synchronized void addItem(String item, int index) {
if (index < -1 || index >= items.size()) {
index = -1;
--- 367,377 ----
* Adds the specified item to the list
* at the position indicated by the index.
*
* @param item the item to be added
* @param index the position at which to add the item
! * @deprecated replaced by {@code add(String, int)}.
*/
@Deprecated
public synchronized void addItem(String item, int index) {
if (index < -1 || index >= items.size()) {
index = -1;
*** 396,406 ****
/**
* Replaces the item at the specified index in the scrolling list
* with the new string.
* @param newValue a new string to replace an existing item
* @param index the position of the item to replace
! * @exception ArrayIndexOutOfBoundsException if <code>index</code>
* is out of range
*/
public synchronized void replaceItem(String newValue, int index) {
remove(index);
add(newValue, index);
--- 396,406 ----
/**
* Replaces the item at the specified index in the scrolling list
* with the new string.
* @param newValue a new string to replace an existing item
* @param index the position of the item to replace
! * @exception ArrayIndexOutOfBoundsException if {@code index}
* is out of range
*/
public synchronized void replaceItem(String newValue, int index) {
remove(index);
add(newValue, index);
*** 416,426 ****
clear();
}
/**
* @deprecated As of JDK version 1.1,
! * replaced by <code>removeAll()</code>.
*/
@Deprecated
public synchronized void clear() {
ListPeer peer = (ListPeer)this.peer;
if (peer != null) {
--- 416,426 ----
clear();
}
/**
* @deprecated As of JDK version 1.1,
! * replaced by {@code removeAll()}.
*/
@Deprecated
public synchronized void clear() {
ListPeer peer = (ListPeer)this.peer;
if (peer != null) {
*** 456,478 ****
* only selected item in the list, the list is set to have no selection.
* @param position the index of the item to delete
* @see #add(String, int)
* @since 1.1
* @exception ArrayIndexOutOfBoundsException
! * if the <code>position</code> is less than 0 or
! * greater than <code>getItemCount()-1</code>
*/
public void remove(int position) {
delItem(position);
}
/**
* Removes the item at the specified position.
*
* @param position the index of the item to delete
! * @deprecated replaced by <code>remove(String)</code>
! * and <code>remove(int)</code>.
*/
@Deprecated
public void delItem(int position) {
delItems(position, position);
}
--- 456,478 ----
* only selected item in the list, the list is set to have no selection.
* @param position the index of the item to delete
* @see #add(String, int)
* @since 1.1
* @exception ArrayIndexOutOfBoundsException
! * if the {@code position} is less than 0 or
! * greater than {@code getItemCount()-1}
*/
public void remove(int position) {
delItem(position);
}
/**
* Removes the item at the specified position.
*
* @param position the index of the item to delete
! * @deprecated replaced by {@code remove(String)}
! * and {@code remove(int)}.
*/
@Deprecated
public void delItem(int position) {
delItems(position, position);
}
*** 480,490 ****
/**
* Gets the index of the selected item on the list,
*
* @return the index of the selected item;
* if no item is selected, or if multiple items are
! * selected, <code>-1</code> is returned.
* @see #select
* @see #deselect
* @see #isIndexSelected
*/
public synchronized int getSelectedIndex() {
--- 480,490 ----
/**
* Gets the index of the selected item on the list,
*
* @return the index of the selected item;
* if no item is selected, or if multiple items are
! * selected, {@code -1} is returned.
* @see #select
* @see #deselect
* @see #isIndexSelected
*/
public synchronized int getSelectedIndex() {
*** 512,522 ****
/**
* Gets the selected item on this scrolling list.
*
* @return the selected item on the list;
* if no item is selected, or if multiple items are
! * selected, <code>null</code> is returned.
* @see #select
* @see #deselect
* @see #isIndexSelected
*/
public synchronized String getSelectedItem() {
--- 512,522 ----
/**
* Gets the selected item on this scrolling list.
*
* @return the selected item on the list;
* if no item is selected, or if multiple items are
! * selected, {@code null} is returned.
* @see #select
* @see #deselect
* @see #isIndexSelected
*/
public synchronized String getSelectedItem() {
*** 542,552 ****
return str;
}
/**
* Gets the selected items on this scrolling list in an array of Objects.
! * @return an array of <code>Object</code>s representing the
* selected items on this scrolling list;
* if no item is selected, a zero-length array is returned.
* @see #getSelectedItems
* @see ItemSelectable
*/
--- 542,552 ----
return str;
}
/**
* Gets the selected items on this scrolling list in an array of Objects.
! * @return an array of {@code Object}s representing the
* selected items on this scrolling list;
* if no item is selected, a zero-length array is returned.
* @see #getSelectedItems
* @see ItemSelectable
*/
*** 561,572 ****
* and will result in unspecified behavior.
*
* <p>Note that this method should be primarily used to
* initially select an item in this component.
* Programmatically calling this method will <i>not</i> trigger
! * an <code>ItemEvent</code>. The only way to trigger an
! * <code>ItemEvent</code> is by user interaction.
*
* @param index the position of the item to select
* @see #getSelectedItem
* @see #deselect
* @see #isIndexSelected
--- 561,572 ----
* and will result in unspecified behavior.
*
* <p>Note that this method should be primarily used to
* initially select an item in this component.
* Programmatically calling this method will <i>not</i> trigger
! * an {@code ItemEvent}. The only way to trigger an
! * {@code ItemEvent} is by user interaction.
*
* @param index the position of the item to select
* @see #getSelectedItem
* @see #deselect
* @see #isIndexSelected
*** 647,658 ****
/**
* Determines if the specified item in this scrolling list is
* selected.
* @param index the item to be checked
! * @return <code>true</code> if the specified item has been
! * selected; <code>false</code> otherwise
* @see #select
* @see #deselect
* @since 1.1
*/
public boolean isIndexSelected(int index) {
--- 647,658 ----
/**
* Determines if the specified item in this scrolling list is
* selected.
* @param index the item to be checked
! * @return {@code true} if the specified item has been
! * selected; {@code false} otherwise
* @see #select
* @see #deselect
* @since 1.1
*/
public boolean isIndexSelected(int index) {
*** 663,673 ****
* Determines if the specified item in the list is selected.
*
* @param index specifies the item to be checked
* @return {@code true} if the item is selected; otherwise {@code false}
* @deprecated As of JDK version 1.1,
! * replaced by <code>isIndexSelected(int)</code>.
*/
@Deprecated
public boolean isSelected(int index) {
int sel[] = getSelectedIndexes();
for (int i = 0 ; i < sel.length ; i++) {
--- 663,673 ----
* Determines if the specified item in the list is selected.
*
* @param index specifies the item to be checked
* @return {@code true} if the item is selected; otherwise {@code false}
* @deprecated As of JDK version 1.1,
! * replaced by {@code isIndexSelected(int)}.
*/
@Deprecated
public boolean isSelected(int index) {
int sel[] = getSelectedIndexes();
for (int i = 0 ; i < sel.length ; i++) {
*** 678,700 ****
return false;
}
/**
* Gets the number of visible lines in this list. Note that
! * once the <code>List</code> has been created, this number
* will never change.
* @return the number of visible lines in this scrolling list
*/
public int getRows() {
return rows;
}
/**
* Determines whether this list allows multiple selections.
*
! * @return <code>true</code> if this list allows multiple
! * selections; otherwise, <code>false</code>
* @see #setMultipleMode
* @since 1.1
*/
public boolean isMultipleMode() {
return allowsMultipleSelections();
--- 678,700 ----
return false;
}
/**
* Gets the number of visible lines in this list. Note that
! * once the {@code List} has been created, this number
* will never change.
* @return the number of visible lines in this scrolling list
*/
public int getRows() {
return rows;
}
/**
* Determines whether this list allows multiple selections.
*
! * @return {@code true} if this list allows multiple
! * selections; otherwise, {@code false}
* @see #setMultipleMode
* @since 1.1
*/
public boolean isMultipleMode() {
return allowsMultipleSelections();
*** 704,714 ****
* Determines whether this list allows multiple selections.
*
* @return {@code true} if this list allows multiple
* selections; otherwise {@code false}
* @deprecated As of JDK version 1.1,
! * replaced by <code>isMultipleMode()</code>.
*/
@Deprecated
public boolean allowsMultipleSelections() {
return multipleMode;
}
--- 704,714 ----
* Determines whether this list allows multiple selections.
*
* @return {@code true} if this list allows multiple
* selections; otherwise {@code false}
* @deprecated As of JDK version 1.1,
! * replaced by {@code isMultipleMode()}.
*/
@Deprecated
public boolean allowsMultipleSelections() {
return multipleMode;
}
*** 719,729 ****
* When the selection mode is changed from multiple-selection to
* single-selection, the selected items change as follows:
* If a selected item has the location cursor, only that
* item will remain selected. If no selected item has the
* location cursor, all items will be deselected.
! * @param b if <code>true</code> then multiple selections
* are allowed; otherwise, only one item from
* the list can be selected at once
* @see #isMultipleMode
* @since 1.1
*/
--- 719,729 ----
* When the selection mode is changed from multiple-selection to
* single-selection, the selected items change as follows:
* If a selected item has the location cursor, only that
* item will remain selected. If no selected item has the
* location cursor, all items will be deselected.
! * @param b if {@code true} then multiple selections
* are allowed; otherwise, only one item from
* the list can be selected at once
* @see #isMultipleMode
* @since 1.1
*/
*** 734,744 ****
/**
* Enables or disables multiple selection mode for this list.
*
* @param b {@code true} to enable multiple mode, {@code false} otherwise
* @deprecated As of JDK version 1.1,
! * replaced by <code>setMultipleMode(boolean)</code>.
*/
@Deprecated
public synchronized void setMultipleSelections(boolean b) {
if (b != multipleMode) {
multipleMode = b;
--- 734,744 ----
/**
* Enables or disables multiple selection mode for this list.
*
* @param b {@code true} to enable multiple mode, {@code false} otherwise
* @deprecated As of JDK version 1.1,
! * replaced by {@code setMultipleMode(boolean)}.
*/
@Deprecated
public synchronized void setMultipleSelections(boolean b) {
if (b != multipleMode) {
multipleMode = b;
*** 749,759 ****
}
}
/**
* Gets the index of the item that was last made visible by
! * the method <code>makeVisible</code>.
* @return the index of the item that was last made visible
* @see #makeVisible
*/
public int getVisibleIndex() {
return visibleIndex;
--- 749,759 ----
}
}
/**
* Gets the index of the item that was last made visible by
! * the method {@code makeVisible}.
* @return the index of the item that was last made visible
* @see #makeVisible
*/
public int getVisibleIndex() {
return visibleIndex;
*** 790,800 ****
* assuming it has the specified number of rows.
*
* @param rows the number of rows
* @return the preferred dimensions for displaying this list
* @deprecated As of JDK version 1.1,
! * replaced by <code>getPreferredSize(int)</code>.
*/
@Deprecated
public Dimension preferredSize(int rows) {
synchronized (getTreeLock()) {
ListPeer peer = (ListPeer)this.peer;
--- 790,800 ----
* assuming it has the specified number of rows.
*
* @param rows the number of rows
* @return the preferred dimensions for displaying this list
* @deprecated As of JDK version 1.1,
! * replaced by {@code getPreferredSize(int)}.
*/
@Deprecated
public Dimension preferredSize(int rows) {
synchronized (getTreeLock()) {
ListPeer peer = (ListPeer)this.peer;
*** 814,824 ****
return preferredSize();
}
/**
* @deprecated As of JDK version 1.1,
! * replaced by <code>getPreferredSize()</code>.
*/
@Deprecated
public Dimension preferredSize() {
synchronized (getTreeLock()) {
return (rows > 0) ?
--- 814,824 ----
return preferredSize();
}
/**
* @deprecated As of JDK version 1.1,
! * replaced by {@code getPreferredSize()}.
*/
@Deprecated
public Dimension preferredSize() {
synchronized (getTreeLock()) {
return (rows > 0) ?
*** 845,855 ****
* with the specified number of rows.
*
* @param rows the number of rows in the list
* @return the minimum dimensions for displaying this list
* @deprecated As of JDK version 1.1,
! * replaced by <code>getMinimumSize(int)</code>.
*/
@Deprecated
public Dimension minimumSize(int rows) {
synchronized (getTreeLock()) {
ListPeer peer = (ListPeer)this.peer;
--- 845,855 ----
* with the specified number of rows.
*
* @param rows the number of rows in the list
* @return the minimum dimensions for displaying this list
* @deprecated As of JDK version 1.1,
! * replaced by {@code getMinimumSize(int)}.
*/
@Deprecated
public Dimension minimumSize(int rows) {
synchronized (getTreeLock()) {
ListPeer peer = (ListPeer)this.peer;
*** 870,880 ****
return minimumSize();
}
/**
* @deprecated As of JDK version 1.1,
! * replaced by <code>getMinimumSize()</code>.
*/
@Deprecated
public Dimension minimumSize() {
synchronized (getTreeLock()) {
return (rows > 0) ? minimumSize(rows) : super.minimumSize();
--- 870,880 ----
return minimumSize();
}
/**
* @deprecated As of JDK version 1.1,
! * replaced by {@code getMinimumSize()}.
*/
@Deprecated
public Dimension minimumSize() {
synchronized (getTreeLock()) {
return (rows > 0) ? minimumSize(rows) : super.minimumSize();
*** 882,893 ****
}
/**
* Adds the specified item listener to receive item events from
* this list. Item events are sent in response to user input, but not
! * in response to calls to <code>select</code> or <code>deselect</code>.
! * If listener <code>l</code> is <code>null</code>,
* no exception is thrown and no action is performed.
* <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
* >AWT Threading Issues</a> for details on AWT's threading model.
*
* @param l the item listener
--- 882,893 ----
}
/**
* Adds the specified item listener to receive item events from
* this list. Item events are sent in response to user input, but not
! * in response to calls to {@code select} or {@code deselect}.
! * If listener {@code l} is {@code null},
* no exception is thrown and no action is performed.
* <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
* >AWT Threading Issues</a> for details on AWT's threading model.
*
* @param l the item listener
*** 908,918 ****
}
/**
* Removes the specified item listener so that it no longer
* receives item events from this list.
! * If listener <code>l</code> is <code>null</code>,
* no exception is thrown and no action is performed.
* <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
* >AWT Threading Issues</a> for details on AWT's threading model.
*
* @param l the item listener
--- 908,918 ----
}
/**
* Removes the specified item listener so that it no longer
* receives item events from this list.
! * If listener {@code l} is {@code null},
* no exception is thrown and no action is performed.
* <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
* >AWT Threading Issues</a> for details on AWT's threading model.
*
* @param l the item listener
*** 931,941 ****
/**
* Returns an array of all the item listeners
* registered on this list.
*
! * @return all of this list's <code>ItemListener</code>s
* or an empty array if no item
* listeners are currently registered
*
* @see #addItemListener
* @see #removeItemListener
--- 931,941 ----
/**
* Returns an array of all the item listeners
* registered on this list.
*
! * @return all of this list's {@code ItemListener}s
* or an empty array if no item
* listeners are currently registered
*
* @see #addItemListener
* @see #removeItemListener
*** 951,961 ****
* Adds the specified action listener to receive action events from
* this list. Action events occur when a user double-clicks
* on a list item or types Enter when the list has the keyboard
* focus.
* <p>
! * If listener <code>l</code> is <code>null</code>,
* no exception is thrown and no action is performed.
* <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
* >AWT Threading Issues</a> for details on AWT's threading model.
*
* @param l the action listener
--- 951,961 ----
* Adds the specified action listener to receive action events from
* this list. Action events occur when a user double-clicks
* on a list item or types Enter when the list has the keyboard
* focus.
* <p>
! * If listener {@code l} is {@code null},
* no exception is thrown and no action is performed.
* <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
* >AWT Threading Issues</a> for details on AWT's threading model.
*
* @param l the action listener
*** 975,985 ****
/**
* Removes the specified action listener so that it no longer
* receives action events from this list. Action events
* occur when a user double-clicks on a list item.
! * If listener <code>l</code> is <code>null</code>,
* no exception is thrown and no action is performed.
* <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
* >AWT Threading Issues</a> for details on AWT's threading model.
*
* @param l the action listener
--- 975,985 ----
/**
* Removes the specified action listener so that it no longer
* receives action events from this list. Action events
* occur when a user double-clicks on a list item.
! * If listener {@code l} is {@code null},
* no exception is thrown and no action is performed.
* <p>Refer to <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
* >AWT Threading Issues</a> for details on AWT's threading model.
*
* @param l the action listener
*** 998,1008 ****
/**
* Returns an array of all the action listeners
* registered on this list.
*
! * @return all of this list's <code>ActionListener</code>s
* or an empty array if no action
* listeners are currently registered
*
* @see #addActionListener
* @see #removeActionListener
--- 998,1008 ----
/**
* Returns an array of all the action listeners
* registered on this list.
*
! * @return all of this list's {@code ActionListener}s
* or an empty array if no action
* listeners are currently registered
*
* @see #addActionListener
* @see #removeActionListener
*** 1015,1050 ****
}
/**
* Returns an array of all the objects currently registered
* as <code><em>Foo</em>Listener</code>s
! * upon this <code>List</code>.
* <code><em>Foo</em>Listener</code>s are registered using the
* <code>add<em>Foo</em>Listener</code> method.
*
* <p>
! * You can specify the <code>listenerType</code> argument
* with a class literal, such as
* <code><em>Foo</em>Listener.class</code>.
* For example, you can query a
! * <code>List</code> <code>l</code>
* for its item listeners with the following code:
*
* <pre>ItemListener[] ils = (ItemListener[])(l.getListeners(ItemListener.class));</pre>
*
* If no such listeners exist, this method returns an empty array.
*
* @param listenerType the type of listeners requested; this parameter
* should specify an interface that descends from
! * <code>java.util.EventListener</code>
* @return an array of all objects registered as
* <code><em>Foo</em>Listener</code>s on this list,
* or an empty array if no such
* listeners have been added
! * @exception ClassCastException if <code>listenerType</code>
* doesn't specify a class or interface that implements
! * <code>java.util.EventListener</code>
*
* @see #getItemListeners
* @since 1.3
*/
public <T extends EventListener> T[] getListeners(Class<T> listenerType) {
--- 1015,1050 ----
}
/**
* Returns an array of all the objects currently registered
* as <code><em>Foo</em>Listener</code>s
! * upon this {@code List}.
* <code><em>Foo</em>Listener</code>s are registered using the
* <code>add<em>Foo</em>Listener</code> method.
*
* <p>
! * You can specify the {@code listenerType} argument
* with a class literal, such as
* <code><em>Foo</em>Listener.class</code>.
* For example, you can query a
! * {@code List l}
* for its item listeners with the following code:
*
* <pre>ItemListener[] ils = (ItemListener[])(l.getListeners(ItemListener.class));</pre>
*
* If no such listeners exist, this method returns an empty array.
*
* @param listenerType the type of listeners requested; this parameter
* should specify an interface that descends from
! * {@code java.util.EventListener}
* @return an array of all objects registered as
* <code><em>Foo</em>Listener</code>s on this list,
* or an empty array if no such
* listeners have been added
! * @exception ClassCastException if {@code listenerType}
* doesn't specify a class or interface that implements
! * {@code java.util.EventListener}
*
* @see #getItemListeners
* @since 1.3
*/
public <T extends EventListener> T[] getListeners(Class<T> listenerType) {
*** 1080,1096 ****
return super.eventEnabled(e);
}
/**
* Processes events on this scrolling list. If an event is
! * an instance of <code>ItemEvent</code>, it invokes the
! * <code>processItemEvent</code> method. Else, if the
! * event is an instance of <code>ActionEvent</code>,
! * it invokes <code>processActionEvent</code>.
* If the event is not an item event or an action event,
! * it invokes <code>processEvent</code> on the superclass.
! * <p>Note that if the event parameter is <code>null</code>
* the behavior is unspecified and may result in an
* exception.
*
* @param e the event
* @see java.awt.event.ActionEvent
--- 1080,1096 ----
return super.eventEnabled(e);
}
/**
* Processes events on this scrolling list. If an event is
! * an instance of {@code ItemEvent}, it invokes the
! * {@code processItemEvent} method. Else, if the
! * event is an instance of {@code ActionEvent},
! * it invokes {@code processActionEvent}.
* If the event is not an item event or an action event,
! * it invokes {@code processEvent} on the superclass.
! * <p>Note that if the event parameter is {@code null}
* the behavior is unspecified and may result in an
* exception.
*
* @param e the event
* @see java.awt.event.ActionEvent
*** 1111,1131 ****
}
/**
* Processes item events occurring on this list by
* dispatching them to any registered
! * <code>ItemListener</code> objects.
* <p>
* This method is not called unless item events are
* enabled for this component. Item events are enabled
* when one of the following occurs:
* <ul>
! * <li>An <code>ItemListener</code> object is registered
! * via <code>addItemListener</code>.
! * <li>Item events are enabled via <code>enableEvents</code>.
* </ul>
! * <p>Note that if the event parameter is <code>null</code>
* the behavior is unspecified and may result in an
* exception.
*
* @param e the item event
* @see java.awt.event.ItemEvent
--- 1111,1131 ----
}
/**
* Processes item events occurring on this list by
* dispatching them to any registered
! * {@code ItemListener} objects.
* <p>
* This method is not called unless item events are
* enabled for this component. Item events are enabled
* when one of the following occurs:
* <ul>
! * <li>An {@code ItemListener} object is registered
! * via {@code addItemListener}.
! * <li>Item events are enabled via {@code enableEvents}.
* </ul>
! * <p>Note that if the event parameter is {@code null}
* the behavior is unspecified and may result in an
* exception.
*
* @param e the item event
* @see java.awt.event.ItemEvent
*** 1142,1162 ****
}
/**
* Processes action events occurring on this component
* by dispatching them to any registered
! * <code>ActionListener</code> objects.
* <p>
* This method is not called unless action events are
* enabled for this component. Action events are enabled
* when one of the following occurs:
* <ul>
! * <li>An <code>ActionListener</code> object is registered
! * via <code>addActionListener</code>.
! * <li>Action events are enabled via <code>enableEvents</code>.
* </ul>
! * <p>Note that if the event parameter is <code>null</code>
* the behavior is unspecified and may result in an
* exception.
*
* @param e the action event
* @see java.awt.event.ActionEvent
--- 1142,1162 ----
}
/**
* Processes action events occurring on this component
* by dispatching them to any registered
! * {@code ActionListener} objects.
* <p>
* This method is not called unless action events are
* enabled for this component. Action events are enabled
* when one of the following occurs:
* <ul>
! * <li>An {@code ActionListener} object is registered
! * via {@code addActionListener}.
! * <li>Action events are enabled via {@code enableEvents}.
* </ul>
! * <p>Note that if the event parameter is {@code null}
* the behavior is unspecified and may result in an
* exception.
*
* @param e the action event
* @see java.awt.event.ActionEvent
*** 1207,1241 ****
* field isn't necessarily up to date, we sync it up with the
* peer before serializing.
*/
/**
! * The <code>List</code> component's
* Serialized Data Version.
*
* @serial
*/
private int listSerializedDataVersion = 1;
/**
* Writes default serializable fields to stream. Writes
! * a list of serializable <code>ItemListeners</code>
! * and <code>ActionListeners</code> as optional data.
* The non-serializable listeners are detected and
* no attempt is made to serialize them.
*
! * @serialData <code>null</code> terminated sequence of 0
! * or more pairs; the pair consists of a <code>String</code>
! * and an <code>Object</code>; the <code>String</code>
* indicates the type of object and is one of the
* following:
! * <code>itemListenerK</code> indicating an
! * <code>ItemListener</code> object;
! * <code>actionListenerK</code> indicating an
! * <code>ActionListener</code> object
*
! * @param s the <code>ObjectOutputStream</code> to write
* @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
* @see java.awt.Component#itemListenerK
* @see java.awt.Component#actionListenerK
* @see #readObject(ObjectInputStream)
*/
--- 1207,1241 ----
* field isn't necessarily up to date, we sync it up with the
* peer before serializing.
*/
/**
! * The {@code List} component's
* Serialized Data Version.
*
* @serial
*/
private int listSerializedDataVersion = 1;
/**
* Writes default serializable fields to stream. Writes
! * a list of serializable {@code ItemListeners}
! * and {@code ActionListeners} as optional data.
* The non-serializable listeners are detected and
* no attempt is made to serialize them.
*
! * @serialData {@code null} terminated sequence of 0
! * or more pairs; the pair consists of a {@code String}
! * and an {@code Object}; the {@code String}
* indicates the type of object and is one of the
* following:
! * {@code itemListenerK} indicating an
! * {@code ItemListener} object;
! * {@code actionListenerK} indicating an
! * {@code ActionListener} object
*
! * @param s the {@code ObjectOutputStream} to write
* @see AWTEventMulticaster#save(ObjectOutputStream, String, EventListener)
* @see java.awt.Component#itemListenerK
* @see java.awt.Component#actionListenerK
* @see #readObject(ObjectInputStream)
*/
*** 1254,1274 ****
AWTEventMulticaster.save(s, actionListenerK, actionListener);
s.writeObject(null);
}
/**
! * Reads the <code>ObjectInputStream</code> and if it
! * isn't <code>null</code> adds a listener to receive
* both item events and action events (as specified
* by the key stored in the stream) fired by the
! * <code>List</code>.
* Unrecognized keys or values will be ignored.
*
! * @param s the <code>ObjectInputStream</code> to write
* @exception HeadlessException if
! * <code>GraphicsEnvironment.isHeadless</code> returns
! * <code>true</code>
* @see #removeItemListener(ItemListener)
* @see #addItemListener(ItemListener)
* @see java.awt.GraphicsEnvironment#isHeadless
* @see #writeObject(ObjectOutputStream)
*/
--- 1254,1274 ----
AWTEventMulticaster.save(s, actionListenerK, actionListener);
s.writeObject(null);
}
/**
! * Reads the {@code ObjectInputStream} and if it
! * isn't {@code null} adds a listener to receive
* both item events and action events (as specified
* by the key stored in the stream) fired by the
! * {@code List}.
* Unrecognized keys or values will be ignored.
*
! * @param s the {@code ObjectInputStream} to write
* @exception HeadlessException if
! * {@code GraphicsEnvironment.isHeadless} returns
! * {@code true}
* @see #removeItemListener(ItemListener)
* @see #addItemListener(ItemListener)
* @see java.awt.GraphicsEnvironment#isHeadless
* @see #writeObject(ObjectOutputStream)
*/
*** 1298,1314 ****
// Accessibility support
////////////////
/**
! * Gets the <code>AccessibleContext</code> associated with this
! * <code>List</code>. For lists, the <code>AccessibleContext</code>
! * takes the form of an <code>AccessibleAWTList</code>.
! * A new <code>AccessibleAWTList</code> instance is created, if necessary.
*
! * @return an <code>AccessibleAWTList</code> that serves as the
! * <code>AccessibleContext</code> of this <code>List</code>
* @since 1.3
*/
public AccessibleContext getAccessibleContext() {
if (accessibleContext == null) {
accessibleContext = new AccessibleAWTList();
--- 1298,1314 ----
// Accessibility support
////////////////
/**
! * Gets the {@code AccessibleContext} associated with this
! * {@code List}. For lists, the {@code AccessibleContext}
! * takes the form of an {@code AccessibleAWTList}.
! * A new {@code AccessibleAWTList} instance is created, if necessary.
*
! * @return an {@code AccessibleAWTList} that serves as the
! * {@code AccessibleContext} of this {@code List}
* @since 1.3
*/
public AccessibleContext getAccessibleContext() {
if (accessibleContext == null) {
accessibleContext = new AccessibleAWTList();
*** 1316,1326 ****
return accessibleContext;
}
/**
* This class implements accessibility support for the
! * <code>List</code> class. It provides an implementation of the
* Java Accessibility API appropriate to list user-interface elements.
* @since 1.3
*/
protected class AccessibleAWTList extends AccessibleAWTComponent
implements AccessibleSelection, ItemListener, ActionListener
--- 1316,1326 ----
return accessibleContext;
}
/**
* This class implements accessibility support for the
! * {@code List} class. It provides an implementation of the
* Java Accessibility API appropriate to list user-interface elements.
* @since 1.3
*/
protected class AccessibleAWTList extends AccessibleAWTComponent
implements AccessibleSelection, ItemListener, ActionListener
*** 1928,1954 ****
public void setSize(Dimension d) {
// not supported; no-op
}
/**
! * Returns the <code>Accessible</code> child, if one exists,
! * contained at the local coordinate <code>Point</code>.
*
* @param p the point relative to the coordinate system of this
* object
! * @return the <code>Accessible</code>, if it exists,
! * at the specified location; otherwise <code>null</code>
*/
public Accessible getAccessibleAt(Point p) {
return null; // object cannot have children!
}
/**
* Returns whether this object can accept focus or not. Objects
* that can accept focus will also have the
! * <code>AccessibleState.FOCUSABLE</code> state set in their
! * <code>AccessibleStateSet</code>.
*
* @return true if object can accept focus; otherwise false
* @see AccessibleContext#getAccessibleStateSet
* @see AccessibleState#FOCUSABLE
* @see AccessibleState#FOCUSED
--- 1928,1954 ----
public void setSize(Dimension d) {
// not supported; no-op
}
/**
! * Returns the {@code Accessible} child, if one exists,
! * contained at the local coordinate {@code Point}.
*
* @param p the point relative to the coordinate system of this
* object
! * @return the {@code Accessible}, if it exists,
! * at the specified location; otherwise {@code null}
*/
public Accessible getAccessibleAt(Point p) {
return null; // object cannot have children!
}
/**
* Returns whether this object can accept focus or not. Objects
* that can accept focus will also have the
! * {@code AccessibleState.FOCUSABLE} state set in their
! * {@code AccessibleStateSet}.
*
* @return true if object can accept focus; otherwise false
* @see AccessibleContext#getAccessibleStateSet
* @see AccessibleState#FOCUSABLE
* @see AccessibleState#FOCUSED
< prev index next >