java::awt::ListBox Class Reference

Inheritance diagram for java::awt::ListBox:

Inheritance graph
java::awt::Componentjava::lang::Objectjava::lang::Interfacejava::lang::Syncjava::awt::event::ComponentSourcejava::awt::event::FocusSourcejava::awt::event::HierarchySourcejava::awt::event::KeySourcejava::awt::event::MouseSourcejava::awt::event::PaintSourcejava::util::PropertyChangeSourcejava::awt::event::ItemSourcejava::lang::Lockjava::lang::ScopeAdapterjava::awt::image::ImageObserverjava::util::EventSourcejava::awt::ItemSelectable
[legend]
Collaboration diagram for java::awt::ListBox:

Collaboration graph
java::awt::Componentjava::lang::Objectjava::lang::Interfacejava::lang::ObjectRefjava::lang::Syncjava::awt::event::ComponentSourcejava::awt::event::FocusSourcejava::awt::event::HierarchySourcejava::awt::event::KeySourcejava::awt::event::MouseSourcejava::awt::event::PaintSourcejava::util::PropertyChangeSourcejava::awt::event::ItemSourcejava::lang::Lockjava::lang::ScopeAdapterjava::lang::Comparablejava::awt::image::ImageObserverjava::util::EventSourcejava::util::Collectionjava::awt::ItemSelectablejava::util::LinkedListjava::util::AbstractSequentialListjava::util::AbstractListjava::util::AbstractCollectionjava::util::List
[legend]

List of all members.


Detailed Description

The ListBox 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.

For example, the code . . .


<blockquote>
 List lst = new ListBox(4, false);
 lst.add("Mercury");
 lst.add("Venus");
 lst.add("Earth");
 lst.add("JavaSoft");
 lst.add("Mars");
 lst.add("Jupiter");
 lst.add("Saturn");
 lst.add("Uranus");
 lst.add("Neptune");
 lst.add("Pluto");
 cnt.add(lst);
 
</blockquote>

where cnt is a container, produces the following scrolling list:

List-1.gif

Clicking on an item that isn't selected selects it. 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 false. Selecting an item causes any other selected item to be automatically deselected.

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 List is created with four rows, so that lst = new List() is equivalent to list = new List(4, false).

Beginning with Java 1.1, the Abstract Window Toolkit sends the 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.)

When an item is selected or deselected by the user, AWT sends an instance of ItemEvent to the list. When the user double-clicks on an item in a scrolling list, AWT sends an instance of 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.

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 ItemListener or ActionListener as appropriate and register the new listener to receive events from this list.

For multiple-selection scrolling lists, it is considered a better user interface to use an external gesture (such as clicking on a button) to trigger the action.

Version:
1.97, 01/23/03
Author:
Sami Shaio
See also:
java.awt.event.ItemEvent

java.awt.event.ItemListener

java.awt.event.ActionEvent

java.awt.event.ActionListener

Since:
JDK1.0

Public Member Functions

 ListBox (jint rows=4, jboolean multipleMode=false)
 Creates a new scrolling list initialized to display the specified number of rows.
virtual jint getItemCount () const
 Gets the number of items in the list.
virtual String getItem (jint index) const
 Gets the item associated with the specified index.
virtual Ref< ListgetItems () const
 Gets the items in the list.
virtual void add (const String &item, jint index=-1)
 Adds the specified item to the the scrolling list at the position indicated by the index.
virtual void replaceItem (const String &newValue, jint index)
 Replaces the item at the specified index in the scrolling list with the new string.
virtual void removeAll ()
 Removes all items from this list.
virtual void remove (const String &item)
 Removes the first occurrence of an item from the list.
virtual void remove (jint position)
 Remove the item at the specified position from this scrolling list.
virtual jint getSelectedIndex () const
 Gets the index of the selected item on the list,.
virtual Array< jintgetSelectedIndexes () const
 Gets the selected indexes on the list.
virtual String getSelectedItem () const
 Gets the selected item on this scrolling list.
virtual Array< StringgetSelectedItems () const
 Gets the selected items on this scrolling list.
virtual Ref< ListgetSelectedObjects () const
 Returns the selected items or null if no items are selected.
virtual void select (jint index)
 Selects the item at the specified index in the scrolling list.
virtual void deselect (jint index)
 Deselects the item at the specified index.
virtual jboolean isIndexSelected (jint index) const
 Determines if the specified item in this scrolling list is selected.
virtual jint getRows () const
 Gets the number of visible lines in this list.
virtual jboolean isMultipleMode () const
 Determines whether this list allows multiple selections.
virtual void setMultipleMode (jboolean b)
 Sets the flag that determines whether this list allows multiple selections.
virtual jint getVisibleIndex () const
 Gets the index of the item that was last made visible by the method makeVisible.
virtual void makeVisible (jint index)
 Makes the item at the specified index visible.
virtual Dimension getPreferredSize (jint rows=0) const
 Gets the preferred dimensions for a list with the specified number of rows.
virtual Dimension getMinimumSize (jint rows=0) const
 Gets the minumum dimensions for a list with the specified number of rows.
virtual String toString () const
 Returns a string representation of this component and its values.

Protected Attributes

 REGISTER_MEMBERS

Constructor & Destructor Documentation

java::awt::ListBox::ListBox ( jint  rows = 4,
jboolean  multipleMode = false 
)

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 multipleMode is true, then the user can select multiple items from the list. If it is false, only one item at a time can be selected.

Parameters:
rows the number of items to show.
multipleMode if true, then multiple selections are allowed; otherwise, only one item can be selected at a time.
Exceptions:
HeadlessException if GraphicsEnvironment.isHeadless() returns true.
See also:
java.awt.GraphicsEnvironment::isHeadless


Member Function Documentation

virtual jint java::awt::ListBox::getItemCount (  )  const [virtual]

Gets the number of items in the list.

Returns:
the number of items in the list
See also:
getItem
Since:
JDK1.1

virtual String java::awt::ListBox::getItem ( jint  index  )  const [virtual]

Gets the item associated with the specified index.

Returns:
an item that is associated with the specified index
Parameters:
index the position of the item
See also:
getItemCount

virtual Ref<List> java::awt::ListBox::getItems (  )  const [virtual]

Gets the items in the list.

Returns:
a string array containing items of the list
See also:
select

deselect

isIndexSelected

Since:
JDK1.1

virtual void java::awt::ListBox::add ( const String item,
jint  index = -1 
) [virtual]

Adds the specified item to the the scrolling list at the position indicated by the index.

The index is 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.

Parameters:
item the item to be added; if this parameter is null then the item is treated as an empty string, ""
index the position at which to add the item
Since:
JDK1.1

virtual void java::awt::ListBox::replaceItem ( const String newValue,
jint  index 
) [virtual]

Replaces the item at the specified index in the scrolling list with the new string.

Parameters:
newValue a new string to replace an existing item
index the position of the item to replace
Exceptions:
ArrayIndexOutOfBoundsException if index is out of range

virtual void java::awt::ListBox::removeAll (  )  [virtual]

Removes all items from this list.

See also:
remove

delItems

Since:
JDK1.1

virtual void java::awt::ListBox::remove ( const String item  )  [virtual]

Removes the first occurrence of an item from the list.

Parameters:
item the item to remove from the list
Exceptions:
IllegalArgumentException if the item doesn't exist in the list
Since:
JDK1.1

virtual void java::awt::ListBox::remove ( jint  position  )  [virtual]

Remove the item at the specified position from this scrolling list.

Parameters:
position the index of the item to delete
See also:
add(String, int)
Since:
JDK1.1
Exceptions:
ArrayIndexOutOfBoundsException if the position is less than 0 or greater than getItemCount()-1

virtual jint java::awt::ListBox::getSelectedIndex (  )  const [virtual]

Gets the index of the selected item on the list,.

Returns:
the index of the selected item, or -1 if no item is selected, or if more that one item is selected
See also:
select

deselect

isIndexSelected

virtual Array<jint> java::awt::ListBox::getSelectedIndexes (  )  const [virtual]

Gets the selected indexes on the list.

Returns:
an array of the selected indexes of this scrolling list; if no items are selected, a zero-length array is returned
See also:
select

deselect

isIndexSelected

virtual String java::awt::ListBox::getSelectedItem (  )  const [virtual]

Gets the selected item on this scrolling list.

Returns:
the selected item on the list, or null if no item is selected
See also:
select

deselect

isIndexSelected

virtual Array<String> java::awt::ListBox::getSelectedItems (  )  const [virtual]

Gets the selected items on this scrolling list.

Returns:
an array of the selected items on this scrolling list
See also:
select

deselect

isIndexSelected

virtual Ref<List> java::awt::ListBox::getSelectedObjects (  )  const [virtual]

Returns the selected items or null if no items are selected.

Implements java::awt::ItemSelectable.

virtual void java::awt::ListBox::select ( jint  index  )  [virtual]

Selects the item at the specified index in the scrolling list.

Note that this method should be primarily used to initially select an item in this component. Programmatically calling this method will not trigger an ItemEvent. The only way to trigger an ItemEvent is by user interaction.

Parameters:
index the position of the item to select
See also:
getSelectedItem

deselect

isIndexSelected

virtual void java::awt::ListBox::deselect ( jint  index  )  [virtual]

Deselects the item at the specified index.

If the item at the specified index is not selected, or if the index is out of range, then the operation is ignored.

Parameters:
index the position of the item to deselect
See also:
select

getSelectedItem

isIndexSelected

virtual jboolean java::awt::ListBox::isIndexSelected ( jint  index  )  const [virtual]

Determines if the specified item in this scrolling list is selected.

Parameters:
index the item to be checked
Returns:
true if the specified item has been selected; false otherwise
See also:
select

deselect

Since:
JDK1.1

virtual jint java::awt::ListBox::getRows (  )  const [virtual]

Gets the number of visible lines in this list.

Note that once the List has been created, this number will never change.

Returns:
the number of visible lines in this scrolling list

virtual jboolean java::awt::ListBox::isMultipleMode (  )  const [virtual]

Determines whether this list allows multiple selections.

Returns:
true if this list allows multiple selections; otherwise, false
See also:
setMultipleMode
Since:
JDK1.1

virtual void java::awt::ListBox::setMultipleMode ( jboolean  b  )  [virtual]

Sets the flag that determines whether this list allows multiple selections.

Parameters:
b if true then multiple selections are allowed; otherwise, only one item from the list can be selected at once
See also:
isMultipleMode
Since:
JDK1.1

virtual jint java::awt::ListBox::getVisibleIndex (  )  const [virtual]

Gets the index of the item that was last made visible by the method makeVisible.

Returns:
the index of the item that was last made visible
See also:
makeVisible

virtual void java::awt::ListBox::makeVisible ( jint  index  )  [virtual]

Makes the item at the specified index visible.

Parameters:
index the position of the item
See also:
getVisibleIndex

virtual Dimension java::awt::ListBox::getPreferredSize ( jint  rows = 0  )  const [virtual]

Gets the preferred dimensions for a list with the specified number of rows.

Parameters:
rows number of rows in the list
Returns:
the preferred dimensions for displaying this scrolling list given that the specified number of rows must be visible
See also:
java.awt.Component::getPreferredSize
Since:
JDK1.1

virtual Dimension java::awt::ListBox::getMinimumSize ( jint  rows = 0  )  const [virtual]

Gets the minumum dimensions for a list with the specified number of rows.

Parameters:
rows number of rows in the list
Returns:
the minimum dimensions for displaying this scrolling list given that the specified number of rows must be visible
See also:
java.awt.Component::getMinimumSize
Since:
JDK1.1

virtual String java::awt::ListBox::toString (  )  const [virtual]

Returns a string representation of this component and its values.

Returns:
a string representation of this component
Since:
JDK1.0

Reimplemented from java::awt::Component.


Member Data Documentation

java::awt::ListBox::REGISTER_MEMBERS [protected]

Reimplemented from java::awt::Component.


The documentation for this class was generated from the following file:
Generated on Fri May 16 11:56:04 2008 for CrossPlatformJavaLikeC++API by  doxygen 1.5.3