## org.ascape.util
Class VectorSelection

    java.lang.Object
      java.util.Observable
          org.ascape.util.VectorSelection

All Implemented Interfaces:
  java.io.Serializable, java.lang.Cloneable, java.util.Observer

Direct Known Subclasses:
  PlatformDrawFeatureSelection

    public class VectorSelection

extends java.util.Observable
implements java.util.Observer, java.lang.Cloneable, java.io.Serializable

A selection imposed on a Vector. Methods are provided for selecting elements, and notifying observers of changes in selction status, but not changes in the underlying vector class. (This class will be generalized for all collections, and collection observer functionality will probably be provided when collections are integrated into the main engine, which should happen after Java 2 (JDK 1.2) becomes commonplace.) Important: because Vectors are not observable, underlying vectors must call the update method on any enclosing vector selection if any changes are made to them. If you want to be able to select Vector elements based on name, implement the HasName interface. Should be thread safe, but not tested. Performance emphasis is on accessing selected elements, not setting selection. Accessing selected elements should be quite fast since an array of selected elements is stored locally.

Since:
  1.0
Version:
  1.9.2 2/5/01
Author:
  Miles Parker
See Also:
  `HasName`, `DataSelection`, Serialized Form

Field Summary
`protected java.util.Vector` `vector` The underlying vector that we are imposing a seleciton upon.

Constructor Summary
`VectorSelection()` Construct a new VectorSelection.
`VectorSelection(java.util.Vector vector)` Construct a new VectorSelection.

Method Summary
`void` `addElement(java.lang.Object object)` Add an elelemnt to the underlying vector.
`void` `addElement(java.lang.Object object, boolean select)` Add an elelemnt to the underlying vector.
`void` `clear()` Sets selection to none, unselecting every element in the vector.
`void` `clearSelection()` Sets selection to none, unselecting every element in the vector.
`java.lang.Object` `clone()` Performs shallow copy, cloning this vector selection, with a shared backing vector.
`int` `getIndexInVector(int index)` Returns the index in the vector of the object at the provided selection index.
`java.lang.Object` `getSelectedElement(int index)` Returns the object at the provided selection index.
`int` `getSelectedIndex(java.lang.Object object)`
`java.lang.Object[]` `getSelection()` Returns the current complete seleciton of vector elements.
`int` `getSelectionSize()` Returns the number of selected elements.
`java.util.Vector` `getVector()` Returns the underlying vector.
`boolean` `isSelected(int index)` Is the object at the supplied index selected in this selection?
`boolean` `isSelected(java.lang.Object elem)` Is the supplied object selected in this selection?
`void` `moveToBack(java.lang.Object elem)`
`void` `moveToFront(java.lang.Object elem)`
`void` `removeElement(java.lang.Object object)` Removes an elemnt from the underlying vector.
`void` `select(java.lang.String name)` Selects the object with the supplied name.
`void` `selectAll()` Selects every element in the vector.
`void` `setSelected(int index, boolean select)` Sets the object at the supplied index to the selection status indicated.
`void` `setSelected(java.lang.Object elem, boolean select)` Sets the supplied object to the selection status indicated.
`void` `setSelected(java.lang.String name, boolean select)` Sets the object with the supplied name to the selection status indicated.
`void` `setVector(java.util.Vector vector)` Set the underlying vector for this selection.
`java.lang.String` `toString()` Returns a string represention of the vector selection.
`void` `unselect(java.lang.String name)` Unselects the object with the supplied name.
`void` `update()` Updates the entire vector, retaining current element selection status and relative selection order.
`void` `update(java.util.Observable observed, java.lang.Object arg)` Normally, notifies the selection that a change in the backing vector has occured.

Methods inherited from class java.util.Observable
`addObserver, clearChanged, countObservers, deleteObserver, deleteObservers, hasChanged, notifyObservers, notifyObservers, setChanged`

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### vector

    protected java.util.Vector vector

  The underlying vector that we are imposing a seleciton upon.

Constructor Detail

### VectorSelection

    public VectorSelection()

  Construct a new VectorSelection.

### VectorSelection

    public VectorSelection(java.util.Vector vector)

  Construct a new VectorSelection.

  Parameters:
    `vector` - the underlying vector

Method Detail

### setVector

    public void setVector(java.util.Vector vector)

  Set the underlying vector for this selection. If any underlying elements are the same as in a previous vector, their selection status should be retained.

### getVector

    public java.util.Vector getVector()

  Returns the underlying vector.

### getSelection

    public java.lang.Object[] getSelection()

  Returns the current complete seleciton of vector elements.

### addElement

    public void addElement(java.lang.Object object,
                           boolean select)

  Add an elelemnt to the underlying vector. Automatically calls update.

  Parameters:
    `object` - the object to add
    `select` - should the object be intitially selected?

### removeElement

    public void removeElement(java.lang.Object object)

  Removes an elemnt from the underlying vector. Automatically calls update.

  Parameters:
    `object` - the object to add

### addElement

    public void addElement(java.lang.Object object)

  Add an elelemnt to the underlying vector. Automatically calls update. Object is initially selected.

### isSelected

    public boolean isSelected(java.lang.Object elem)

  Is the supplied object selected in this selection?

  Parameters:
    `elem` - the object to determine selection status for
  Returns:
    true if the item is selected, false if the item is not selected or is not in the list

### isSelected

    public boolean isSelected(int index)

  Is the object at the supplied index selected in this selection?

  Parameters:
    `index` - the vector index of the object to determine selection status for
  Returns:
    true if the item is selected

### selectAll

    public void selectAll()

  Selects every element in the vector.

### clearSelection

    public void clearSelection()

  Sets selection to none, unselecting every element in the vector.

### clear

    public void clear()

  Sets selection to none, unselecting every element in the vector.

### select

    public void select(java.lang.String name)

  Selects the object with the supplied name.

  Parameters:
    `name` - the name of the series to set select status for

### unselect

    public void unselect(java.lang.String name)

  Unselects the object with the supplied name.

  Parameters:
    `name` - the name of the series to set select status for

### setSelected

    public void setSelected(int index,
                            boolean select)

  Sets the object at the supplied index to the selection status indicated.

  Parameters:
    `index` - the vector index of the object to set select status for
    `select` - true to select the item, false to unselect it

### setSelected

    public void setSelected(java.lang.String name,
                            boolean select)

  Sets the object with the supplied name to the selection status indicated. Warning: Expects Vector members to implement of `HaveName`.

  Parameters:
    `name` - the name of the series to set select status for
    `select` - true to select the item, false to unselect it
  Throws:
    `java.lang.ClassCastException` - if vector elements are not instances of HaveName

### setSelected

    public void setSelected(java.lang.Object elem,
                            boolean select)

  Sets the supplied object to the selection status indicated.

  Parameters:
    `elem` - the object to set selection status for
    `select` - true to select the item, false to unselect it
  Throws:
    `java.lang.RuntimeException` - if the element does not exist in the vector

### getSelectionSize

    public int getSelectionSize()

  Returns the number of selected elements.

### getIndexInVector

    public int getIndexInVector(int index)

  Returns the index in the vector of the object at the provided selection index.

  Parameters:
    `index` - the selection index to get the vector index for

### getSelectedIndex

    public int getSelectedIndex(java.lang.Object object)

### getSelectedElement

    public java.lang.Object getSelectedElement(int index)

  Returns the object at the provided selection index.

  Parameters:
    `index` - the index in this selection of the series

### update

    public void update(java.util.Observable observed,
                       java.lang.Object arg)

  Normally, notifies the selection that a change in the backing vector has occured. Not used at the moment, because Vector isn't observable. Will probably be implmented when java collections are fully implemeneted in ascape.

  Specified by:
    `update` in interface `java.util.Observer`

### update

    public void update()

  Updates the entire vector, retaining current element selection status and relative selection order. May be costly, especially for large collections, as this class is optimized for the selection access case. Calls to this method may be batched, that is, you can make a number of changes to the underlying vector and call update one time.

### clone

    public java.lang.Object clone()

  Performs shallow copy, cloning this vector selection, with a shared backing vector.

  Overrides:
    `clone` in class `java.lang.Object`

### moveToFront

    public void moveToFront(java.lang.Object elem)

### moveToBack

    public void moveToBack(java.lang.Object elem)

### toString

    public java.lang.String toString()

  Returns a string represention of the vector selection.

  Overrides:
    `toString` in class `java.lang.Object`