sub_arctic.input
Class click_agent

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

public class click_agent

extends dispatch_agent

implements click_tracking

A positional dispatch agent responsible for managing press/release, click, and double click interactions. This agent dispatches under three different input protocols: pressable (which does single presses and releases of a mouse button), clickable (which is a press and a release of a mouse button), and double_clickable (which is two rapid clicks in a small area). Note: that if the dispatch of a click is consumed, this resets the internal finite state controller and precludes delivery of a subsequent click as a double click. Similarly, if a press or release is consumed, those events will not form part of a click dispatch.

See Also:

pressable, clickable, double_clickable

Field Summary

protected java.lang.reflect.Method	click The method object that represents click
protected static int	CLICK_CLOSE Constant indicating how close together (in both x and y) events have to be to qualify as parts of the same click/double-click.
protected java.lang.reflect.Method	doubleclick The method object that represents double click
protected int	first_x X location of first press in sequence (in global coordinates).
protected int	first_y Y location of first press in sequence (in global coordinates).
protected int	last_evt_seq Sequence number of last event processed
protected int	last_press_release_anywhere Sequence number of last press or release we monitored
protected java.lang.reflect.Method	press The method object that represents press
protected java.lang.reflect.Method	release The method object that represents release
protected int	state State for finite state controller.

Constructor Summary

click_agent()
Default constructor

Method Summary

boolean	dispatch_event(event evt, java.lang.Object user_info, interactor to_obj, int seq_num) Accept an event from the positional policy and attempt to dispatch it to an object.
protected boolean	do_dispatches(interactor to_obj, event evt, java.lang.Object user_info) Attempt to perform event dispatch(es) to the given object, resetting the state to the start state when appropriate (see comments for make_transition).
boolean	event_is_useful(event evt) We are only interested in press and release of the mouse button.
void	focus_set_enter(event evt, focus_dispatch_agent agnt, java.lang.Object user_info) Part of protocol for click_tracking which we use to be informed about button presses or releases that occur and are consumed elsewhere.
void	focus_set_exit(event evt, focus_dispatch_agent agnt, java.lang.Object user_info) Part of protocol for click_tracking which we use to be informed about button presses or releases that occur and are consumed elsewhere.
protected void	make_transition(event evt) This method makes state transitions for a finite state machine controlling the interaction.
protected boolean	matches_first(event next_event) Determine if event qualifies as close enough to match first event in a sequence.
boolean	track_click(event evt, java.lang.Object user_info) Track press and release events everywhere that are dispatched to us from the click_track monitoring agent.

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

state

protected int state

State for finite state controller. States are: 0 start state, have seen nothing yet. 1 have seen press 2 have seen release 3 have dispatched press and release as a click 4 have seen second press after click 5 have seen second press and release after click

last_evt_seq

protected int last_evt_seq

Sequence number of last event processed

last_press_release_anywhere

protected int last_press_release_anywhere

Sequence number of last press or release we monitored

first_x

protected int first_x

X location of first press in sequence (in global coordinates). We use this for proximity tests.

first_y

protected int first_y

Y location of first press in sequence (in global coordinates). We use this for proximity tests.

press

protected java.lang.reflect.Method press

The method object that represents press

release

protected java.lang.reflect.Method release

The method object that represents release

click

protected java.lang.reflect.Method click

The method object that represents click

doubleclick

protected java.lang.reflect.Method doubleclick

The method object that represents double click

CLICK_CLOSE

protected static final int CLICK_CLOSE

Constant indicating how close together (in both x and y) events have to be to qualify as parts of the same click/double-click.

Constructor Detail

click_agent

public click_agent()

Default constructor

Method Detail

focus_set_enter

public void focus_set_enter(event evt,
                            focus_dispatch_agent agnt,
                            java.lang.Object user_info)

Part of protocol for click_tracking which we use to be informed about button presses or releases that occur and are consumed elsewhere. Here we happen to ignore this.

focus_set_exit

public void focus_set_exit(event evt,
                           focus_dispatch_agent agnt,
                           java.lang.Object user_info)

Part of protocol for click_tracking which we use to be informed about button presses or releases that occur and are consumed elsewhere. Here we happen to ignore this.

event_is_useful

public boolean event_is_useful(event evt)

We are only interested in press and release of the mouse button.

Parameters:

event - evt the event we are indicating interest or non-interest in.

Overrides:

event_is_useful in class dispatch_agent

matches_first

protected boolean matches_first(event next_event)

Determine if event qualifies as close enough to match first event in a sequence. We do this by comparing against the previously saved position of the first event in the sequence.

Parameters:

event - next_event event whose position we are testing

track_click

public boolean track_click(event evt,
                           java.lang.Object user_info)

Track press and release events everywhere that are dispatched to us from the click_track monitoring agent. We record the event sequence number of this event and if we don't see a matching event then we know somebody else got it first and so we reset our state. We detect this by noting that we get a new event but the previous one was never processed.

Specified by:

track_click in interface click_tracking

Parameters:

event - evt the press or release event.

Object - user_info user_info associated with the even dispatch (ignored here).

make_transition

protected void make_transition(event evt)

This method makes state transitions for a finite state machine controlling the interaction. This is a complicated state machine in which three kinds of transitions can be made. Each new event moves to a new state (via this method). In addition, if an event actually causes a dispatch, a transition back to the start state (0) may occur (within dispatch_event). Finally, in certain states (2 and 5 -- corresponding to a single release or a completed double-click respectively) if the event is *not* dispatched the machine is also reset to the start state. Since we can't actually tell when an event will not be dispatched (e.g., we can't tell if the positional policy will call us again with the same event), this final class of transition is actually handled when the *next* event arrives. This corresponds to doing two transitions here.

Parameters:

event - evt the event potentially causing the transition.

do_dispatches

protected boolean do_dispatches(interactor to_obj,
                                event evt,
                                java.lang.Object user_info)

Attempt to perform event dispatch(es) to the given object, resetting the state to the start state when appropriate (see comments for make_transition).

Parameters:

interactor - to_obj the object we are trying to dispatch to.

event - evt the event to pass to the object.

Object - user_info uninterpreted user info to pass to the object.

Returns:

boolean whether the event has been dispatched and consumed.

See Also:

make_transition(sub_arctic.input.event)

dispatch_event

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

Accept an event from the positional policy and attempt to dispatch it to an object.

Parameters:

event - evt the event being dispatched.

Object - user_info uninterpreted information to be passed to the object.

interactor - to_obj the object we should attempt to dispatch to.

int - seq_num the sequence number of this event (so we can tell if we have seen this before in a failed attempt to dispatch it to another object).

Returns:

boolean indicating whether the event was dispatched and consumed.

Overrides:

dispatch_event in class dispatch_agent