sub_arctic.input
Class focus_dispatch_agent

java.lang.Object
  |
  +--sub_arctic.input.dispatch_agent
        |
        +--sub_arctic.input.focus_dispatch_agent
Direct Known Subclasses:
click_track_agent, menu_focus_agent, raw_focus_agent, single_focus_agent, window_agent

public abstract class focus_dispatch_agent
extends dispatch_agent

This is the abstract base class for all focus dispatch agents. It provides infrastructure for maintaining objects in focus sets, notifying objects of entry and exit from the focus set, etc. This (partial) agent dispatches input under the focusable input protocol.

See Also:
focusable

Field Summary
protected  java.util.Vector _focus_set
          Focus set.
protected  java.util.Vector _user_info_set
          Each focus object may provide a user info object when it is placed in the focus set.
 
Constructor Summary
focus_dispatch_agent()
           
 
Method Summary
 void add_to_focus(focusable new_obj, event evt, java.lang.Object user_info)
          Add an object to the focus set of this agent.
 boolean allowable_focus(focusable candidate_obj)
          Do subclass specific test to see if the given object is eligible to go in the focus set.
 void clear_focus(event evt)
          Clear the focus set of this agent to empty.
abstract  boolean dispatch_event(event evt, java.lang.Object user_info, interactor to_obj, int seq_num)
          Attempt to dispatch an event to an object or set of objects via this agent.
 focusable focus_item(int at_indx)
          Return the focus object at a given index in the focus set vector.
 int focus_set_size()
          Indicate the size of the current focus set.
protected  void inform_focus_enter(focusable obj, event evt, java.lang.Object user_info)
          This method is called whenever an object enters the focus set.
protected  void inform_focus_exit(focusable obj, event evt, java.lang.Object user_info)
          This method is called whenever an object exits the focus set.
 boolean is_in_focus(focusable obj)
          Determine if the given object is currently part of the focus set for this agent.
 void remove_from_focus(focusable obj, event evt)
          Remove the given object from the focus set of this agent.
 void set_focus_to(focusable to_obj, event evt, java.lang.Object user_info)
          Replace the focus set of this agent with the given object.
protected  java.lang.Object user_info_item(int at_indx)
          Retrieve the user info object corresponding to the focusable object at the given index.
 
Methods inherited from class sub_arctic.input.dispatch_agent
after_dispatch_notify, dispatch_unused_event, event_is_useful
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

_focus_set

protected java.util.Vector _focus_set
Focus set. This contains focusable objects and maintains all objects that are currently in the focus set for this agent. This list is maintained in synch with _user_info_set which contains the user info objects belonging to each object in the focus set.

_user_info_set

protected java.util.Vector _user_info_set
Each focus object may provide a user info object when it is placed in the focus set. This vector maintains the set of those objects corresponding the interactor objects in the current focus set. Positions in this vector correspond directly to positions in _focus_set. This vector contains objects of any type.
Constructor Detail

focus_dispatch_agent

public focus_dispatch_agent()
Method Detail

focus_set_size

public int focus_set_size()
Indicate the size of the current focus set.

focus_item

public focusable focus_item(int at_indx)
Return the focus object at a given index in the focus set vector.
Parameters:
int - at_indx the index of the requested object.

user_info_item

protected java.lang.Object user_info_item(int at_indx)
Retrieve the user info object corresponding to the focusable object at the given index.
Parameters:
int - at_indx the index of the requested object.

inform_focus_enter

protected void inform_focus_enter(focusable obj,
                                  event evt,
                                  java.lang.Object user_info)
This method is called whenever an object enters the focus set. It calls focus_set_enter() on the object (as part of the focusable input protocol). Note: in some subclass agents, the focus_set_enter() call is replaced by a more specific call particular to the protocol managed by that agent.

Parameters:
focusable - obj the object entering the focus set.
event - evt the event that "caused" the entry.
Object - user_info the user info associated with that object.

inform_focus_exit

protected void inform_focus_exit(focusable obj,
                                 event evt,
                                 java.lang.Object user_info)
This method is called whenever an object exits the focus set. It calls focus_set_exit() on the object (as part of the focusable input protocol). Note: in some subclass agents, the focus_set_exit() call is replaced by a more specific call particular to the protocol managed by that agent.

Parameters:
focusable - obj the object exiting the focus set.
event - evt the event that "caused" the exit.
Object - user_info the user info associated with that object.

allowable_focus

public boolean allowable_focus(focusable candidate_obj)
Do subclass specific test to see if the given object is eligible to go in the focus set. Typically we would test that the object implements the interface that defines the input dispatch protocol in question. Here in the superclass we let anything in.

Parameters:
focusable - candidate_obj object we are accepting or rejecting
Returns:
boolean indicating if the object is suitable for inclusion in the focus set.

set_focus_to

public void set_focus_to(focusable to_obj,
                         event evt,
                         java.lang.Object user_info)
Replace the focus set of this agent with the given object. This provides a causal event and an uninterpreted object that will be passed back to the focus object whenever input is delivered to it by this agent.

Parameters:
focusable - to_obj the object going in the focus set.
event - evt the event that "caused" this focus.
Object - user_info the uninterpreted information that we will pass back to the object whenever it gets input from this agent.

is_in_focus

public boolean is_in_focus(focusable obj)
Determine if the given object is currently part of the focus set for this agent.

Parameters:
focusable - obj the object we are asking about
Returns:
boolean indicating whether the object is in the focus set.

add_to_focus

public void add_to_focus(focusable new_obj,
                         event evt,
                         java.lang.Object user_info)
Add an object to the focus set of this agent. This provides a causal event and an uninterpreted object that will be passed back to the focus object whenever input is delivered to it by this agent.

Parameters:
focusable - to_obj the object going in the focus set.
event - evt the event that "caused" this focus.
Object - user_info the uninterpreted information that we will pass back to the object whenever it gets input from this agent.

remove_from_focus

public void remove_from_focus(focusable obj,
                              event evt)
Remove the given object from the focus set of this agent.
Parameters:
focusable - obj the object to be removed.
event - evt the event that "caused" this removal.

clear_focus

public void clear_focus(event evt)
Clear the focus set of this agent to empty.
Parameters:
event - evt the event that "caused" this.

dispatch_event

public abstract boolean dispatch_event(event evt,
                                       java.lang.Object user_info,
                                       interactor to_obj,
                                       int seq_num)
Attempt to dispatch an event to an object or set of objects via this agent. The event is passed in all cases. In our case (for focus agents), the remaining parameters are ignored as we store the user_info and object to dispatch to internally, and are not passed the same event more than once. This method is overridden by each subclass to do its specific work.

Parameters:
event - evt the event to be dispatched.
Object - user_info ignored.
interactor - to_obj ignored.
int - seq_num ignored.
Overrides:
dispatch_event in class dispatch_agent