sub_arctic.input
Class navigation_agent

java.lang.Object
  |
  +--sub_arctic.input.dispatch_agent
        |
        +--sub_arctic.input.focus_dispatch_agent
              |
              +--sub_arctic.input.single_focus_agent
                    |
                    +--sub_arctic.input.navigation_agent

public class navigation_agent
extends single_focus_agent

Focus based dispatch agent for catching keyboard based input and turning it into tree navigation input (under the navigable input protocol). This is driven from a table of key to action translations which define which keys do what (in terms calls under the dispatch protocol). A default table is provided, but this can be reset. Actions which can be listed in the table include:

NAV_UP
move up one level in the tree
NAV_DOWN
move down to the first child
NAV_RIGHT
move right to the next sibling
NAV_LEFT
move left to the previous sibling
NAV_TOP
move to the top of the tree
PREV_UP
preview a move up
PREV_DOWN
preview a move down
PREV_RIGHT
preview a move right
PREV_LEFT
preview a move left
PREV_TOP
preview a move to the top of the tree
START_TEXT_MODE
start text entry mode. Further text (except the keystroke used to end text entry mode) will be ignored and hence will be passed on to other text based agents for handling.
END_TEXT_MODE
end text entry mode and resume normal processing of keyboard input as navigation commands.
DO_ACTION_0
perform the primary action associated with the location.
DO_ACTION_1
perform the secondary action associated with the location.
DO_ACTION_2
perform the 3rd action associated with the location.
DO_ACTION_3
perform the 4th action associated with the location. The table consists of sets of 5 integers. Each set of 5 integers includes: input_code, key_code, character, modifiers, and action<\i>. Where code is an event code (for keys this would be KEY_PRESSED for the mouse button this would be MOUSE_PRESSED). Key_code is a value to match against the key_code field of an event (or VK_UNDEFINED if any value is ok). Typical values here would be LEFT, RIGHT, UP, and DOWN indicating the respective arrow keys. Character is an expected unicode character (or CHAR_UNDEFINED if any character should match). Modifiers is zero or more of the values: ALT_MASK, CTRL_MASK, META_MASK, or SHIFT_MASK ORed together (matching events must contain exactly the listed modifier bits), and finally action is one of the action codes listed above. Note: the table is searched in order, so if you have overlapping but more specific entries (e.g., using the same key as another, but with a modifier) the more specific entry must come first.

To work properly this should sit in front of the text_acceptor agent so it gets first crack at text input.

See Also:
sub_arctic.input.navigation_acceptor

Field Summary
protected  int[] _action_table
          The action table which controls translation from events to calls under the navigable protocol.
protected static int[] _default_table
          The default action table.
protected  boolean _in_text_mode
          Are we currently in text entry mode
static int DO_ACTION_0
          Action code for "perform the primary action associated with location"
static int DO_ACTION_1
          Action code for "perform the secondary action associated with location"
static int DO_ACTION_2
          Action code for "perform the 3rd action associated with location"
static int DO_ACTION_3
          Action code for "perform the 4th action associated with location"
protected  java.lang.reflect.Method down
          Hold a reference to the Method for down.
static int END_TEXT_MODE
          Action code for "end text entry mode"
protected  java.lang.reflect.Method enter_text
          Hold a reference to the Method for entering text mode.
protected  java.lang.reflect.Method exit_text
          Hold a reference to the Method for exiting text mode;
static int LAST_VALID_ACTION_CODE
          Last valid action code (valid codes run from 0 to this value)
protected  java.lang.reflect.Method left
          Hold a reference to the Method for left;
static int NAV_DOWN
          Action code for "move down to the first child"
static int NAV_LEFT
          Action code for "move left to the previous sibling"
static int NAV_RIGHT
          Action code for "move right to the next sibling"
static int NAV_TOP
          Action code for "move to the top of the tree"
static int NAV_UP
          Action code for "move up one level in the tree"
protected  java.lang.reflect.Method perform_action
          Hold a reference to the Method for performing actions.
static int PREV_DOWN
          Action code for "preview a move down"
static int PREV_LEFT
          Action code for "preview a move left"
static int PREV_RIGHT
          Action code for "preview a move right"
static int PREV_TOP
          Action code for "preview a move to the top of the tree"
static int PREV_UP
          Action code for "preview a move up"
protected  java.lang.reflect.Method preview_down
          Hold a reference to the Method for preview_down.
protected  java.lang.reflect.Method preview_left
          Hold a reference to the Method for preview_left;
protected  java.lang.reflect.Method preview_right
          Hold a reference to the Method for preview_right.
protected  java.lang.reflect.Method preview_to_top
          Hold a reference to the Method for preview_to_top.
protected  java.lang.reflect.Method preview_up
          Hold a reference to the Method for previw_up.
protected  java.lang.reflect.Method right
          Hold a reference to the Method for right.
static int START_TEXT_MODE
          Action code for "start text entry mode"
protected  java.lang.reflect.Method to_top
          Hold a reference to the Method for to_top.
protected  java.lang.reflect.Method up
          Hold a reference to the Method for up.
 
Fields inherited from class sub_arctic.input.focus_dispatch_agent
_focus_set, _user_info_set
 
Constructor Summary
navigation_agent()
          Constructor that provides a default action table.
navigation_agent(int[] action_tab)
          Full constructor.
 
Method Summary
 int[] action_table()
          The action table which controls translation from events to calls under the navigable protocol.
 boolean allowable_focus(focusable candidate_obj)
          Indicate whether the given object is suitable to be our focus.
 boolean dispatch_event(event evt, java.lang.Object user_info, interactor to_obj, int seq_num)
          Attempt to dispatch the given event as text input.
 boolean event_is_useful(event evt)
          Indicate if the given event is (possibly) wanted by this agent.
 void set_action_table(int[] new_tab)
          Set the action table which controls translation from events to calls under the navigable protocol.
 
Methods inherited from class sub_arctic.input.single_focus_agent
add_to_focus, clear_focus, remove_from_focus, set_focus_to
 
Methods inherited from class sub_arctic.input.focus_dispatch_agent
focus_item, focus_set_size, inform_focus_enter, inform_focus_exit, is_in_focus, user_info_item
 
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

up

protected java.lang.reflect.Method up
Hold a reference to the Method for up.

down

protected java.lang.reflect.Method down
Hold a reference to the Method for down.

left

protected java.lang.reflect.Method left
Hold a reference to the Method for left;

right

protected java.lang.reflect.Method right
Hold a reference to the Method for right.

to_top

protected java.lang.reflect.Method to_top
Hold a reference to the Method for to_top.

preview_up

protected java.lang.reflect.Method preview_up
Hold a reference to the Method for previw_up.

preview_down

protected java.lang.reflect.Method preview_down
Hold a reference to the Method for preview_down.

preview_left

protected java.lang.reflect.Method preview_left
Hold a reference to the Method for preview_left;

preview_right

protected java.lang.reflect.Method preview_right
Hold a reference to the Method for preview_right.

preview_to_top

protected java.lang.reflect.Method preview_to_top
Hold a reference to the Method for preview_to_top.

enter_text

protected java.lang.reflect.Method enter_text
Hold a reference to the Method for entering text mode.

exit_text

protected java.lang.reflect.Method exit_text
Hold a reference to the Method for exiting text mode;

perform_action

protected java.lang.reflect.Method perform_action
Hold a reference to the Method for performing actions.

NAV_UP

public static final int NAV_UP
Action code for "move up one level in the tree"

NAV_DOWN

public static final int NAV_DOWN
Action code for "move down to the first child"

NAV_RIGHT

public static final int NAV_RIGHT
Action code for "move right to the next sibling"

NAV_LEFT

public static final int NAV_LEFT
Action code for "move left to the previous sibling"

NAV_TOP

public static final int NAV_TOP
Action code for "move to the top of the tree"

PREV_UP

public static final int PREV_UP
Action code for "preview a move up"

PREV_DOWN

public static final int PREV_DOWN
Action code for "preview a move down"

PREV_RIGHT

public static final int PREV_RIGHT
Action code for "preview a move right"

PREV_LEFT

public static final int PREV_LEFT
Action code for "preview a move left"

PREV_TOP

public static final int PREV_TOP
Action code for "preview a move to the top of the tree"

START_TEXT_MODE

public static final int START_TEXT_MODE
Action code for "start text entry mode"

END_TEXT_MODE

public static final int END_TEXT_MODE
Action code for "end text entry mode"

DO_ACTION_0

public static final int DO_ACTION_0
Action code for "perform the primary action associated with location"

DO_ACTION_1

public static final int DO_ACTION_1
Action code for "perform the secondary action associated with location"

DO_ACTION_2

public static final int DO_ACTION_2
Action code for "perform the 3rd action associated with location"

DO_ACTION_3

public static final int DO_ACTION_3
Action code for "perform the 4th action associated with location"

LAST_VALID_ACTION_CODE

public static final int LAST_VALID_ACTION_CODE
Last valid action code (valid codes run from 0 to this value)

_default_table

protected static int[] _default_table
The default action table. This table has the following mappings:
UP key
navigate_up()
DOWN key
navigate_up()
LEFT key
navigate_left()
RIGHT key
navigate_right()
HOME key
navigate_to_top()
Holding down the shift key previews the above listed moves
F1 key
enter_text_entry_mode() and exit_text_entry_mode()
SPACE key
do_action_0()
RETURN key
do_action_1()
SPACE key with CONTROL held down
do_action_2()
RETURN key with CONTROL held down
do_action_3()

_action_table

protected int[] _action_table
The action table which controls translation from events to calls under the navigable protocol. The table consists of sets of of 5 integers. These integers encode how keyboard (or other) input is translated into calls in the navagable input protocol. Each set of 5 integers includes: code, key_code, character, modifiers, and action. Where code is an event code (typically KEY_PRESSED for character, or MOUSE_PRESSED for a mouse button down event), key_code is a value to match against the key_code field of an event (or VK_UNDEFINED if any value is ok), character indicates an expected unicode character (or CHAR_UNDEFINED if any character will do), modifiers is zero or more of the values: ALT_MASK, CTRL_MASK, META_MASK, or SHIFT_MASK ORed together (matching events must contain exactly the listed modifier bits), and finally action is one of the action code constants declared in this class. Note: the table is searched in order, so if you have overlapping but more specific entries (e.g., using the same key as another, but with a modifier) the more specific entry must come first.

If this table is null, no events are accepted.


_in_text_mode

protected boolean _in_text_mode
Are we currently in text entry mode
Constructor Detail

navigation_agent

public navigation_agent(int[] action_tab)
Full constructor.
Parameters:
int[] - action_table an array containing sets of 5 integers. These integers encode how keyboard (or other) input is translated into calls in the navagable input protocol. Each set of 5 integers includes: code, key_code, character, modifiers, and action. Where code is an event code (typically KEY_PRESSED for character, or MOUSE_PRESSED for a mouse button down event), key_code is a value to match against the key_code field of an event (or VK_UNDEFINED if any value is ok), character indicates an expected unicode character (or CHAR_UNDEFINED if any character code is ok), modifiers is zero or more of the values: ALT_MASK, CTRL_MASK, META_MASK, or SHIFT_MASK ORed together (matching events must contain all the listed modifier bits), and finally action is one of the action code constants declared in this class. Note: the table is searched in order, so if you have overlapping but more specific entries (e.g., using the same key as another, but with a modifier) the more specific entry must come first.

navigation_agent

public navigation_agent()
Constructor that provides a default action table.
See Also:
_default_table
Method Detail

action_table

public int[] action_table()
The action table which controls translation from events to calls under the navigable protocol. The table consists of sets of of 5 integers. These integers encode how keyboard (or other) input is translated into calls in the navagable input protocol. Each set of 5 integers includes: code, key_code, character, modifiers, and action. Where code is an event code (typically KEY_PRESSED for character, or MOUSE_PRESSED for a mouse button down event), key_code is a value to match against the key_code field of an event (or VK_UNDEFINED if any value is ok), character indicates an expected unicode character (or CHAR_UNDEFINED if any character will do), modifiers is zero or more of the values: ALT_MASK, CTRL_MASK, META_MASK, or SHIFT_MASK ORed together (matching events must contain exactly the listed modifier bits), and finally action is one of the action code constants declared in this class. Note: the table is searched in order, so if you have overlapping but more specific entries (e.g., using the same key as another, but with a modifier) the more specific entry must come first.

If this table is null, no events are accepted. If you need to change this array, be certain to pass it back to set_action_table() after the change in order to update internal bookkeeping.

Returns:
int[] the current action table

set_action_table

public void set_action_table(int[] new_tab)
Set the action table which controls translation from events to calls under the navigable protocol. If this table is set to null, no events will be accepted.
Parameters:
int[] - the new action table
See Also:
action_table()

allowable_focus

public boolean allowable_focus(focusable candidate_obj)
Indicate whether the given object is suitable to be our focus. In this case it needs to be a navibable object.
Parameters:
focusable - candidate_obj the object being inquired about.
Returns:
boolean indicating if the object is suitable.
Overrides:
allowable_focus in class focus_dispatch_agent

event_is_useful

public boolean event_is_useful(event evt)
Indicate if the given event is (possibly) wanted by this agent.
Parameters:
event - evt the event being inquired about.
Returns:
boolean indicating if we want the event.
Overrides:
event_is_useful in class dispatch_agent

dispatch_event

public boolean dispatch_event(event evt,
                              java.lang.Object user_info,
                              interactor to_obj,
                              int seq_num)
Attempt to dispatch the given event as text input.
Parameters:
event - evt the event to dispatch.
Object - user_info ignored (since we are focus agent).
interactor - to_obj ignored (since we are focus agent).
int - seq_num ignored (since we are focus agent).
Returns:
boolean indicating if the input was consumed.
Overrides:
dispatch_event in class focus_dispatch_agent