sub_arctic.input
Class selection_agent_class

java.lang.Object
  |
  +--sub_arctic.input.dispatch_agent
        |
        +--sub_arctic.input.selection_agent_class

public class selection_agent_class

extends dispatch_agent

Positional dispatch agent for maintaining a currently selected set. This agent dispatches inputs under the selectable input protocol and maintains a currently selected object set. Objects can be placed in the set by clicking on them using a Macintosh style interaction where simple clicks make objects the single selection, and clicks with the shift key held down add to the set.

See Also:

selectable

Field Summary

protected java.util.Vector	_selection_set The currently selected set.
protected java.lang.reflect.Method	select Hold a reference to the select function of our protocol.
protected java.lang.reflect.Method	unselect Hold a reference to the unselect function of our protocol.

Constructor Summary

selection_agent_class()
Simple constructor

Method Summary

boolean	add_to_selection_set(selectable obj, event evt, java.lang.Object user_info) Add the given object to the selection set.
void	clear_selection_set(event evt, java.lang.Object user_info) Clear the selection set to empty.
boolean	dispatch_event(event evt, java.lang.Object user_info, interactor to_obj, int seq_num) Attempt to dispatch an event with this agent.
boolean	event_is_useful(event evt) Indicate which events we are interested in seeing.
int	find_selection(selectable obj) Return the index of the given object in the currently selected object set or -1 if the object is not selected.
protected boolean	inform_addition(selectable obj, event evt, java.lang.Object user_info) Do the work of informing an object that it has been added to the currently selected object set.
protected boolean	inform_removal(selectable obj, event evt, java.lang.Object user_info) Do the work of informing an object that it has been removed from the currently selected object set.
int	num_selected() Number of objects currently selected
boolean	remove_from_selection_set(selectable obj, event evt, java.lang.Object user_info) Remove the given object to the selection set.
selectable	selected_set_item(int index) Retrieve the selected object at the given index in the currently selected set.
boolean	set_selection(selectable obj, event evt, java.lang.Object user_info) Set the selection set to the given single element.

Methods inherited from class sub_arctic.input.dispatch_agent

after_dispatch_notify, dispatch_unused_event

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

select

protected java.lang.reflect.Method select

Hold a reference to the select function of our protocol.

unselect

protected java.lang.reflect.Method unselect

Hold a reference to the unselect function of our protocol.

_selection_set

protected java.util.Vector _selection_set

The currently selected set. This vector contains selectable objects.

Constructor Detail

selection_agent_class

public selection_agent_class()

Simple constructor

Method Detail

num_selected

public int num_selected()

Number of objects currently selected

selected_set_item

public selectable selected_set_item(int index)

Retrieve the selected object at the given index in the currently selected set.

Parameters:

int - index the index of the desired element.

Returns:

selectable the desired element

clear_selection_set

public void clear_selection_set(event evt,
                                java.lang.Object user_info)

Clear the selection set to empty.

Parameters:

event - evt the event which "caused" the clear.

Object - user_info the user information that should be passed to objects dropping out of the selection set.

set_selection

public boolean set_selection(selectable obj,
                             event evt,
                             java.lang.Object user_info)

Set the selection set to the given single element. Objects have the option of rejecting selection (by returning false from select(), in which case this routine returns false and the selection set is left as is.

Parameters:

selectable - obj the object being selected

event - evt the event which "caused" the selection.

Object - user_info the user information that should be passed to objects added and dropped out of the selection set.

Returns:

boolean indicating if the object accepted the selection.

find_selection

public int find_selection(selectable obj)

Return the index of the given object in the currently selected object set or -1 if the object is not selected.

Parameters:

selectable - obj the object we are inquiring about.

Returns:

int the index of the object in the currently selected object set or -1 if it is not currently selected.

add_to_selection_set

public boolean add_to_selection_set(selectable obj,
                                    event evt,
                                    java.lang.Object user_info)

Add the given object to the selection set. Objects have the option of rejecting selection (by returning false from select(), in which case this routine returns false and the selection set is left as is.

Parameters:

selectable - obj the object being selected

event - evt the event which "caused" the selection.

Object - user_info the user information that should be passed to object added to the selection set.

Returns:

boolean indicating if the object accepted the selection.

remove_from_selection_set

public boolean remove_from_selection_set(selectable obj,
                                         event evt,
                                         java.lang.Object user_info)

Remove the given object to the selection set. False is returned if the object is not in the selection set, or if the object's unselect() method returns false (however, the object is always removed from the selection set).

Parameters:

selectable - obj the object being deselected

event - evt the event which "caused" the deselection.

Object - user_info the user information that should be passed to object dropped out of the selection set.

Returns:

boolean indicating if the object accepted the selection.

event_is_useful

public boolean event_is_useful(event evt)

Indicate which events we are interested in seeing. We are only interested in presses of the mouse button.

Parameters:

event - evt the event we are testing.

Returns:

boolean indicating whether we want to see the event.

Overrides:

event_is_useful in class dispatch_agent

inform_addition

protected boolean inform_addition(selectable obj,
                                  event evt,
                                  java.lang.Object user_info)

Do the work of informing an object that it has been added to the currently selected object set. Returns the result of the select() call on the object. Note: this routine does not put the object in the set.

Parameters:

selectable - obj the object we are informing.

event - evt the event "causing" the selection.

Object - user_info the user info that should be passed to the object.

Returns:

boolean which was the result of the object's select() method.

inform_removal

protected boolean inform_removal(selectable obj,
                                 event evt,
                                 java.lang.Object user_info)

Do the work of informing an object that it has been removed from the currently selected object set. Returns the result of the unselect() call on the object. Note: this routine does not remove the object from the set.

Parameters:

selectable - obj the object we are informing.

event - evt the event "causing" the deselection.

Object - user_info the user info that should be passed to the object.

Returns:

boolean which was the result of the object's unselect() method.

dispatch_event

public boolean dispatch_event(event evt,
                              java.lang.Object user_info,
                              interactor to_obj,
                              int seq_num)

Attempt to dispatch an event with this agent. Mouse presses with the shift key held down add to the currently selected object set. Plain presses replace the currently selected object set with a single object.

Parameters:

event - evt the event we are trying to dispatch

Object - user_info the user info value to pass with the dispatch

interactor - to_obj the object to dispatch to.

int - seq_num the sequence number of this event.

Returns:

boolean indicating whether the event was consumed.

Overrides:

dispatch_event in class dispatch_agent