com.nwoods.jgo
Class JGoSelection

java.lang.Object
  extended bycom.nwoods.jgo.JGoSelection
All Implemented Interfaces:
JGoObjectSimpleCollection, java.io.Serializable

public class JGoSelection
extends java.lang.Object
implements JGoObjectSimpleCollection, java.io.Serializable

JGoSelection holds the collection of a JGoDocument's JGoObjects that are currently selected in a JGoView.

Each JGoView has a single JGoSelection object, and each JGoSelection object knows about its view.

JGoSelection is responsible for maintaining JGoHandles for the selected objects. These handles are view objects--they are part of this particular view and are not part of the underlying document.

JGoSelection implements Serializable so that it can be used with drag-and-drop and the clipboard. Serialized objects will not be compatible with future JGo releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of JGo.

See Also:
JGoDocument, Serialized Form

Constructor Summary
JGoSelection()
          JGoSelection objects are automatically created for each JGoView.
JGoSelection(JGoView view)
          JGoSelection objects are automatically created for each JGoView by JGoView.createDefaultSelection().
 
Method Summary
 void addArray(JGoObject[] a)
          Add the JGoObjects in the given array at the end of this list.
 void addCollection(java.util.ArrayList a)
          Add the JGoObjects in the given ArrayList at the end of this list.
 void addCollection(JGoObjectSimpleCollection c)
          Add the JGoObjects in the given collection at the end of this list.
 void addHandle(JGoObject obj, JGoHandle handle)
          Keep track of a new handle and add it to the selection's view.
 JGoHandle allocateResizeHandle(JGoObject obj, int x, int y, int handleType)
          This method is called by createResizeHandle to actually allocate a JGoHandle of the appropriate size at the given position.
 void clearSelection()
          Remove all currently selected objects from the selection.
 void clearSelection(JGoObject obj)
          Make sure the given object is no longer in this selection.
 void clearSelectionHandles(JGoObject obj)
          Hide all the selection handles for the given object.
 JGoHandle createBoundingHandle(JGoObject obj)
          This method creates the single default handle for a non-resizable object.
 JGoHandle createResizeHandle(JGoObject obj, int x, int y, int handleType, boolean filled)
          This method creates a single handle for a resizable object, associates it with the selected object, and initializes its appearance by setting its pen and brush.
 void deleteHandles(JGoObject obj)
          Remove all the handles for the given object.
 JGoObject extendSelection(JGoObject obj)
          Add the given object to this selection, ignoring duplicates.
 JGoListPosition getFirstObjectPos()
          Return the position of the first object in the collection.
 JGoListPosition getNextObjectPos(JGoListPosition pos)
          Return the position for the next object in the collection.
 JGoListPosition getNextObjectPosAtTop(JGoListPosition pos)
          Return the position for the next top-level object in the collection.
 int getNumHandles(JGoObject obj)
          Return how many selection handles exist for the given object.
 int getNumObjects()
          Return the number of top-level objects in the collection.
 JGoObject getObjectAtPos(JGoListPosition pos)
          Return the object for the given position.
 JGoObject getPrimarySelection()
          Return the first object of the selection, or else return null if the selection is empty.
 JGoView getView()
          Return the view that this selection belongs to.
 void hideHandles(JGoObject obj)
          Hide the existing handles for the given selected object.
 boolean isEmpty()
          Return true if there are no objects in the collection.
 boolean isInSelection(JGoObject obj)
          This predicate returns true if the given object (perhaps "redirected") is a selected object.
 boolean isResizeHandleSizeInViewCoords()
          Return whether the dimensions of a newly allocated resize handle should be in document coordinates (false) or in view coordinates (true).
 boolean isSelected(JGoObject obj)
          This predicate is true if the given object is a selected object.
 void restoreSelectionHandles(JGoObject obj)
          Show all the selection handles for the given object.
 JGoObject selectObject(JGoObject obj)
          Make the given object the only object in this selection.
 void setResizeHandleSizeInViewCoords(boolean b)
          Control whether a newly allocated resize handle should always appear the same size, regardless of the view's scale, or whether the resize handle should be scaled along with all the other objects.
 void showHandles(JGoObject obj)
          Make visible the existing handles for the given selected object.
 JGoObject[] toArray()
          Return the selected objects as an array of JGoObjects.
 JGoObject toggleSelection(JGoObject obj)
          If the given object is currently in this selection, remove it, or else add it to this selection.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JGoSelection

public JGoSelection()
JGoSelection objects are automatically created for each JGoView.


JGoSelection

public JGoSelection(JGoView view)
JGoSelection objects are automatically created for each JGoView by JGoView.createDefaultSelection().

Method Detail

getView

public final JGoView getView()
Return the view that this selection belongs to.


getNumObjects

public int getNumObjects()
Description copied from interface: JGoObjectSimpleCollection
Return the number of top-level objects in the collection.

Specified by:
getNumObjects in interface JGoObjectSimpleCollection

isEmpty

public boolean isEmpty()
Description copied from interface: JGoObjectSimpleCollection
Return true if there are no objects in the collection.

Specified by:
isEmpty in interface JGoObjectSimpleCollection

getFirstObjectPos

public JGoListPosition getFirstObjectPos()
Description copied from interface: JGoObjectSimpleCollection
Return the position of the first object in the collection. This will be null if the list is empty.

Specified by:
getFirstObjectPos in interface JGoObjectSimpleCollection

getObjectAtPos

public JGoObject getObjectAtPos(JGoListPosition pos)
Description copied from interface: JGoObjectSimpleCollection
Return the object for the given position.

Specified by:
getObjectAtPos in interface JGoObjectSimpleCollection
Parameters:
pos - the position of an object in the collection.
Returns:
the object for this position in the collection.

getNextObjectPos

public JGoListPosition getNextObjectPos(JGoListPosition pos)
Description copied from interface: JGoObjectSimpleCollection
Return the position for the next object in the collection. This may recurse through the objects contained by a JGoArea.

Specified by:
getNextObjectPos in interface JGoObjectSimpleCollection
Parameters:
pos - the position previous to that which will be returned.
Returns:
an iterator for the next object in the collection; null if there are no more objects.

getNextObjectPosAtTop

public JGoListPosition getNextObjectPosAtTop(JGoListPosition pos)
Description copied from interface: JGoObjectSimpleCollection
Return the position for the next top-level object in the collection. A top-level JGoObject is one which is not contained in any JGoArea objects.

Specified by:
getNextObjectPosAtTop in interface JGoObjectSimpleCollection
Parameters:
pos - the position from which to start searching for the next top-level object.
Returns:
an iterator for the next top-level object in the collection; null if there are no more objects.

getPrimarySelection

public JGoObject getPrimarySelection()
Return the first object of the selection, or else return null if the selection is empty.


selectObject

public JGoObject selectObject(JGoObject obj)
Make the given object the only object in this selection.

Any previous objects in the selection will be removed from the selection (but not from the document).

The object's redirectSelection() method is called to give it the opportunity to determine that another object really ought to take its place in the selection. If redirectSelection() returns null, no object is added to the selection. The (possibly redirected) object to be added to the selection normally must belong to the selection's view's document.

Registered JGoViewListeners will get SELECTION_LOST events for all the objects that had been in the selection, and will get a SELECTION_GAINED event for the newly selected object if it was not already the only selected object.

Parameters:
obj - a document object
Returns:
the selected object

extendSelection

public JGoObject extendSelection(JGoObject obj)
Add the given object to this selection, ignoring duplicates.

The object's redirectSelection() method is called to give it the opportunity to determine that another object really ought to take its place in the selection. If redirectSelection() returns null, no object is added to the selection. The (possibly redirected) object to be added to the selection normally must belong to the selection's view's document.

If the object is already in the selection, we just return the object.

Registered JGoViewListeners will get a SELECTION_GAINED event for the newly selected object.

Parameters:
obj - a document object

toggleSelection

public JGoObject toggleSelection(JGoObject obj)
If the given object is currently in this selection, remove it, or else add it to this selection.

All JGoViewListeners will receive a SELECTION_LOST or SELECTION_GAINED event for the given object.

Parameters:
obj - a document object

clearSelection

public void clearSelection(JGoObject obj)
Make sure the given object is no longer in this selection.

All JGoViewListeners will receive a SELECTION_LOST event for the given object.

Parameters:
obj - a document object

clearSelection

public void clearSelection()
Remove all currently selected objects from the selection.

All JGoViewListeners will receive SELECTION_LOST events for each object.


isInSelection

public boolean isInSelection(JGoObject obj)
This predicate returns true if the given object (perhaps "redirected") is a selected object.

The object's redirectSelection() method is called to give it the opportunity to determine that another object really ought to considered for checking the selection. If redirectSelection() returns null, this predicate returns false.

Parameters:
obj - a document object

isSelected

public boolean isSelected(JGoObject obj)
This predicate is true if the given object is a selected object. The object's redirectSelection() method is not called.

Parameters:
obj - a document object

toArray

public JGoObject[] toArray()
Return the selected objects as an array of JGoObjects.


addArray

public void addArray(JGoObject[] a)
Add the JGoObjects in the given array at the end of this list.

This just calls extendSelection repeatedly. Duplicate objects will be ignored.

Parameters:
a - an array of JGoObjects

addCollection

public void addCollection(java.util.ArrayList a)
Add the JGoObjects in the given ArrayList at the end of this list.

This just calls extendSelection repeatedly. Duplicate objects will be ignored.

Parameters:
a - an ArrayList of JGoObjects

addCollection

public void addCollection(JGoObjectSimpleCollection c)
Add the JGoObjects in the given collection at the end of this list.

This just calls extendSelection repeatedly. Duplicate objects will be ignored.

Parameters:
c - any JGoObjectSimpleCollection, such as a JGoCollection, a JGoDocument, or a JGoLayer

clearSelectionHandles

public void clearSelectionHandles(JGoObject obj)
Hide all the selection handles for the given object.

If the object is null, all selection handles for all selected objects are hidden.

Parameters:
obj - a selected document object or null

restoreSelectionHandles

public void restoreSelectionHandles(JGoObject obj)
Show all the selection handles for the given object.

If the object is null, all selection handles for all selected objects are shown.

Parameters:
obj - a selected document object or null

showHandles

public void showHandles(JGoObject obj)
Make visible the existing handles for the given selected object.

Parameters:
obj - a selected document object

hideHandles

public void hideHandles(JGoObject obj)
Hide the existing handles for the given selected object.

Parameters:
obj - a selected document object

createBoundingHandle

public JGoHandle createBoundingHandle(JGoObject obj)
This method creates the single default handle for a non-resizable object.

Parameters:
obj - a selected document object

isResizeHandleSizeInViewCoords

public boolean isResizeHandleSizeInViewCoords()
Return whether the dimensions of a newly allocated resize handle should be in document coordinates (false) or in view coordinates (true). The default value is false.


setResizeHandleSizeInViewCoords

public void setResizeHandleSizeInViewCoords(boolean b)
Control whether a newly allocated resize handle should always appear the same size, regardless of the view's scale, or whether the resize handle should be scaled along with all the other objects.

A true value means the initial resize handle size is measured in view coordinates, so that the resize handle appears to be the normal size even though the view is zoomed in or out from the normal scale. A false value means the initial resize handle will appear scaled along with all the other objects.

In either case, if the view's scale changes after the handle has been allocated, the handle will scale correspondingly. If you really want to keep all resize handles the same size even as the view's scale changes, you'll need to implement a view listener that notices the scale change and resizes the handles appropriately.


allocateResizeHandle

public JGoHandle allocateResizeHandle(JGoObject obj,
                                      int x,
                                      int y,
                                      int handleType)
This method is called by createResizeHandle to actually allocate a JGoHandle of the appropriate size at the given position.

By default this method creates a new JGoHandle of a standard size centered at the given position. If isResizeHandleSizeInViewCoords() is true, then the size is determined by the view's current scale.

Parameters:
obj - the object for which the handle is being created
x - the X position for the new handle
y - the Y position for the new handle
handleType - the kind of handle to be created
See Also:
JGoHandle

createResizeHandle

public JGoHandle createResizeHandle(JGoObject obj,
                                    int x,
                                    int y,
                                    int handleType,
                                    boolean filled)
This method creates a single handle for a resizable object, associates it with the selected object, and initializes its appearance by setting its pen and brush.

Parameters:
obj - a selected document object
x - the X position for the new handle
y - the Y position for the new handle
handleType - the kind of handle to be created
filled - determines whether a null brush or the PrimarySelectionColor or SecondarySelectionColor is used inside the handle

addHandle

public void addHandle(JGoObject obj,
                      JGoHandle handle)
Keep track of a new handle and add it to the selection's view. This method also makes sure the handle's associated object, the handleFor property, is also the selected object.

Parameters:
obj - the selected document object for which we are adding a handle
handle - a newly created handle

deleteHandles

public void deleteHandles(JGoObject obj)
Remove all the handles for the given object.

Parameters:
obj - a selected document object

getNumHandles

public int getNumHandles(JGoObject obj)
Return how many selection handles exist for the given object. This method does not call redirectSelection().

This returns zero if the object is not selected. It may return zero even if the object is selected, either because gainedSelection() has been overridden for that object not to create any selection handles, or because the handles have been deleted (perhaps because the object is now not Visible).