sub_arctic.input
Class dispatch_agent

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

Direct Known Subclasses:

animation_agent, click_agent, event_trace_agent, focus_dispatch_agent, grow_press_drag_agent, inout_press_drag_agent, move_press_drag_agent, point_agent_class, raw_positional_agent, selection_agent_class, simple_press_drag_agent, work_agent

public abstract class dispatch_agent

extends java.lang.Object

This is the abstract base class for all dispatch agents in all policies. This API provides methods for reporting whether the agent is interested in a particular type of event, for actually dispatching the event.

Constructor Summary

dispatch_agent()
Construct a dispatch agent.

Method Summary

void	after_dispatch_notify(event evt, boolean dispatched) This method is called by the manager after an event is dispatched on all agents which have registered interest in becoming aware of this fact.
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 via this agent.
boolean	dispatch_unused_event(event evt) This method is called by some policies (most notably the positional policy) to dispatch events which did not meet the selection criteria of the policy itself.
boolean	event_is_useful(event evt) Indicate whether the given event might be dispatchable by this agent.

Methods inherited from class java.lang.Object

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

Constructor Detail

dispatch_agent

public dispatch_agent()

Construct a dispatch agent.

Method Detail

event_is_useful

public boolean event_is_useful(event evt)

Indicate whether the given event might be dispatchable by this agent. Events will not be delivered to the agent unless they pass this test. Here in the base class we accept everything.

Parameters:

event - evt the event to be tested for usefulness

Returns:

boolean true if the event is one this agent is interested in

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 via this agent. The event is passed in all cases. For some policies (e.g.,the positional policy), an object to dispatch to and a bit of user supplied information (typically this was returned by the object at the time it was picked) can be given. In other cases null is passed for these to parameters.

In addition, for agents which may be passed the same event more than once (targeted towards different objects), a sequence number is also passed. This number is guaranteed to be different for each different event being dispatched (this allows the agent to know when to clear its cache or advance within its state machine controller in certain cases).

Parameters:

event - evt the event to dispatch

Object - user_info policy defined user information

interactor - to_obj the object to (possibly)send the event to

int - seq_num the sequence number of this event

dispatch_unused_event

public boolean dispatch_unused_event(event evt)

This method is called by some policies (most notably the positional policy) to dispatch events which did not meet the selection criteria of the policy itself. This is necessary for some agents, as they have state machines that depend on knowing when the "next" event occurs, even if that event is not over any object on the interface.

The most common use of this is to remove status displays when the pointer leaves the area of an application via an agent like pointable.

The default implementation of this function is to simply return false.

Parameters:

event - evt the event to dispatch

Returns:

boolean true is returned if the event is dispatched

after_dispatch_notify

public void after_dispatch_notify(event evt,
                                  boolean dispatched)

This method is called by the manager after an event is dispatched on all agents which have registered interest in becoming aware of this fact. You can register for interest using manager.add_to_after_dispatch_list().

Note that there is no return value from the function, because it is not possible to affect the event -- it has already been dispatched (or not dispatched) when this function is called.

By default this function does nothing.

Parameters:

event - evt the event which was dispatched (or not)

boolean - dispatched true if the event was handled by some agent