sub_arctic.new_lib
Class navigator_base

java.lang.Object
  |
  +--sub_arctic.new_lib.navigator_base

Direct Known Subclasses:

halo_navigator

public class navigator_base

extends java.lang.Object

implements navigable

This class provides a simple base class for objects which represents a current position within an interactor tree and provide an API for moving that position around in the tree (i.e., implement navigable).

Field Summary

protected interactor

_current_location The current location of the navigator in the tree.

Constructor Summary

navigator_base(interactor cur_loc)
Construct a navigator based on an initial position in the tree.

Method Summary

void	arrive(interactor at_interactor) Provide feedback and/or actions associated with arriving at a particular interactor node.
interactor	current_location() The current location of the navigator in the tree.
void	depart(interactor from_interactor) Provide feedback and/or actions associated with leaving a particular interactor node.
protected boolean	do_move(interactor target) Do a local area move to the given target object.
protected boolean	do_preview(interactor target) Do the preview for a local area move to the given target object.
boolean	enter_text_entry_mode(event evt, java.lang.Object user_info) Request to enter text entry mode.
boolean	exit_text_entry_mode(event evt, java.lang.Object user_info) Indicate that we are leaving text entry mode and returning to navigation mode.
protected interactor	find_down(interactor from_loc) Find the next node moving down, returning null if we hit the bottom.
protected interactor	find_left(interactor from_loc) Find the next node moving left, returning null if we go beyond the first child.
protected interactor	find_right(interactor from_loc) Find the next node moving right, returning null if we go beyond the last child.
protected interactor	find_up(interactor from_loc) Find the next node moving up, returning null if we hit the top.
void	focus_set_enter(event cause_evt, focus_dispatch_agent of_agent, java.lang.Object user_info) Method called when we go in the focus set.
void	focus_set_exit(event cause_evt, focus_dispatch_agent of_agent, java.lang.Object user_info) Method called when we go in the focus set.
void	hit_bottom() Provide feedback for attempting to move down past a leaf.
void	hit_left() Provide feedback for attempting to move left past the first sibling.
void	hit_right() Provide feedback for attempting to move right past the last sibling.
void	hit_top() Provide feedback for attempting to move up past the root.
boolean	navigate_down(event evt, java.lang.Object user_info) Navigate downwards in the tree (move to first child).
boolean	navigate_left(event evt, java.lang.Object user_info) Navigate left in the tree (move to the previous sibling).
boolean	navigate_right(event evt, java.lang.Object user_info) Navigate right in the tree (move to the next sibling).
boolean	navigate_to_top(event evt, java.lang.Object user_info) Navigate to the root of the tree.
void	navigate_to(interactor target_location) Move the current location to an arbitrary interactor
boolean	navigate_up(event evt, java.lang.Object user_info) Navigate upwards in the tree (move to the parent).
boolean	perform_action(int act_num, event evt, java.lang.Object user_info) Do an associated with the interactor at the current location.
void	preview_arrive(interactor at_interactor) Provide preview feedback associated with arriving at a particular interactor node.
void	preview_depart(interactor from_interactor) Provide preview feedback associated with leaving a particular interactor node.
boolean	preview_down(event evt, java.lang.Object user_info) Perform a preview of the actions that would be taken on a navigate_down().
void	preview_hit_bottom() Provide preview feedback for attempting to move down past a leaf.
void	preview_hit_left() Provide preview feedback for attempting to move left past the first sibling.
void	preview_hit_right() Provide preview feedback for attempting to move right past the last sibling.
void	preview_hit_top() Provide preview feedback for attempting to move up past the root.
boolean	preview_left(event evt, java.lang.Object user_info) Perform a preview of the actions that would be taken on a navigate_left().
boolean	preview_right(event evt, java.lang.Object user_info) Perform a preview of the actions that would be taken on a navigate_right().
boolean	preview_to_top(event evt, java.lang.Object user_info) Perform a preview of the actions that would be taken on a navigate_to_top().
void	preview_to(interactor target_location) Perform a preview of the actions that moving to an arbitrary interactor would do.
boolean	preview_up(event evt, java.lang.Object user_info) Perform a preview of the actions that would be taken on a navigate_up().

Methods inherited from class java.lang.Object

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

Field Detail

_current_location

protected interactor _current_location

The current location of the navigator in the tree.

Constructor Detail

navigator_base

public navigator_base(interactor cur_loc)

Construct a navigator based on an initial position in the tree.

Parameters:

interactor - cur_loc initial location for the navigator

Method Detail

current_location

public interactor current_location()

The current location of the navigator in the tree.

Returns:

interactor the object the navigator is currenly located at.

navigate_to

public void navigate_to(interactor target_location)

Move the current location to an arbitrary interactor

Parameters:

interactor - target_location the position in the tree we should move to

find_up

protected interactor find_up(interactor from_loc)

Find the next node moving up, returning null if we hit the top. Here in the base class this is simply the parent. In subclasses some nodes may be invisible or collapsed with respect to navigation.

Parameters:

interactor - from_loc the interactor we are moving up from

Returns:

interactor the next interactor in the up direction, or null if we hit the top

find_down

protected interactor find_down(interactor from_loc)

Find the next node moving down, returning null if we hit the bottom. Here in the base class this is simply the first child. In subclasses some nodes may be invisible or collapsed with respect to navigation.

Parameters:

interactor - from_loc the interactor we are moving down from

Returns:

interactor the next interactor in the down direction, or null if we hit the bottom

find_left

protected interactor find_left(interactor from_loc)

Find the next node moving left, returning null if we go beyond the first child. Here in the base class this is simply the previous sibling. In subclasses some nodes may be invisible or collapsed with respect to navigation.

Parameters:

interactor - from_loc the interactor we are moving left from

Returns:

interactor the next interactor in the down direction, or null if we go past the first child

find_right

protected interactor find_right(interactor from_loc)

Find the next node moving right, returning null if we go beyond the last child. Here in the base class this is simply the next sibling. In subclasses some nodes may be invisible or collapsed with respect to navigation.

Parameters:

interactor - from_loc the interactor we are moving right from

Returns:

interactor the next interactor in the down direction, or null if we go past the last child

do_move

protected boolean do_move(interactor target)

Do a local area move to the given target object. This will do the required depart() and arrive() calls as needed. If this returns false, then the move failed (probably because the passed in target location hadn't been found and was null), and an alternate action may be needed.

Parameters:

interactor - target the interactor we are moving to

Returns:

boolean indicating whether the move worked (== true) or we need to do an alternate action (== false).

navigate_up

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

Navigate upwards in the tree (move to the parent). If the navigator is at the top of the tree this will call hit_top(), but probably do nothing else. In other cases, this will call depart() and arrive() as needed.

Specified by:

navigate_up in interface navigable

Parameters:

event - evt the event causing this input

Object - user_info information supplied at focus time

Returns:

boolean indicating whether input was accepted

navigate_down

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

Navigate downwards in the tree (move to first child). If the navigator is at a leaf this will call hit_bottom(), but probably do nothing else. In other cases, this will call depart() and arrive() as needed.

Specified by:

navigate_down in interface navigable

Parameters:

event - evt the event causing this input

Object - user_info information supplied at focus time

Returns:

boolean indicating whether input was accepted

navigate_left

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

Navigate left in the tree (move to the previous sibling). If the navigator is at the first sibling this will call hit_left(), but probably do nothing else. In other cases, this will call depart() and arrive() as needed.

Specified by:

navigate_left in interface navigable

Parameters:

event - evt the event causing this input

Object - user_info information supplied at focus time

Returns:

boolean indicating whether input was accepted

navigate_right

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

Navigate right in the tree (move to the next sibling). If the navigator is at the last sibling this will call hit_right(), but probably do nothing else. In other cases, this will call depart() and arrive() as needed.

Specified by:

navigate_right in interface navigable

Parameters:

event - evt the event causing this input

Object - user_info information supplied at focus time

Returns:

boolean indicating whether input was accepted

navigate_to_top

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

Navigate to the root of the tree. This should be equivalent to a series of one or more navigate_up() calls. If the navigator is already at the root this will call hit_top(), but probably do nothing else. In other cases, this will call depart() and arrive() as needed.

Specified by:

navigate_to_top in interface navigable

Parameters:

event - evt the event causing this input

Object - user_info information supplied at focus time

Returns:

boolean indicating whether input was accepted

do_preview

protected boolean do_preview(interactor target)

Do the preview for a local area move to the given target object. This will do the required preview_depart() and preview_arrive() calls as needed. If this returns false, then the move fails (probably because the passed in target location hadn't been found and was null), and an alternate preview action may be needed.

Parameters:

interactor - target the interactor we are previewing the moving to

Returns:

boolean indicating whether the move works (== true) or we need to do an alternate action (== false).

preview_to

public void preview_to(interactor target_location)

Perform a preview of the actions that moving to an arbitrary interactor would do. This will call preview_depart() and preview_arrive() as needed. This operation may be ignored by navigators which do not do previews.

Parameters:

interactor - target_location the position in the tree we should preview to.

preview_up

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

Perform a preview of the actions that would be taken on a navigate_up(). If the navigator is at the top of the tree this will call preview_hit_top(). This will call preview_depart() and preview_arrive() as needed. This operation may be ignored by navigators which do not do previews.

Specified by:

preview_up in interface navigable

Parameters:

event - evt the event causing this input

Object - user_info information supplied at focus time

Returns:

boolean indicating whether input was accepted

preview_down

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

Perform a preview of the actions that would be taken on a navigate_down(). If the navigator is at a leaf in the tree this will call preview_hit_bottom(). This will call preview_depart() and preview_arrive() as needed. This operation may be ignored by navigators which do not do previews.

Specified by:

preview_down in interface navigable

Parameters:

event - evt the event causing this input

Object - user_info information supplied at focus time

Returns:

boolean indicating whether input was accepted

preview_left

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

Perform a preview of the actions that would be taken on a navigate_left(). If the navigator is at the first sibling this will call preview_hit_left(). This will call preview_depart() and preview_arrive() as needed. This operation may be ignored by navigators which do not do previews.

Specified by:

preview_left in interface navigable

Parameters:

event - evt the event causing this input

Object - user_info information supplied at focus time

Returns:

boolean indicating whether input was accepted

preview_right

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

Perform a preview of the actions that would be taken on a navigate_right(). If the navigator is at the first sibling this will call preview_hit_right(). This will call preview_depart() and preview_arrive() as needed. This operation may be ignored by navigators which do not do previews.

Specified by:

preview_right in interface navigable

Parameters:

event - evt the event causing this input

Object - user_info information supplied at focus time

Returns:

boolean indicating whether input was accepted

preview_to_top

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

Perform a preview of the actions that would be taken on a navigate_to_top(). This should be equivalent to a series of one or more preview_up() calls. If the navigator is already at the root this will call preview_hit_top(). This operation may be ignored by navigators which do not do previews.

Specified by:

preview_to_top in interface navigable

Parameters:

event - evt the event causing this input

Object - user_info information supplied at focus time

Returns:

boolean indicating whether input was accepted

enter_text_entry_mode

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

Request to enter text entry mode. In this mode, keystrokes that might normally be interpreted by the input agent as navigation commands are treated as normal keystrokes again. If the current interactor does not accept text, text_entry_mode_fail() will be called, and false will be returned (indicating that the input agent should not enter text entry mode). Here in the base class this always succeeds (returns true), but otherwise does nothing.

Specified by:

enter_text_entry_mode in interface navigable

Parameters:

event - evt the event causing this input

Object - user_info information supplied at focus time

Returns:

boolean indicating successful entry into text entry mode.

exit_text_entry_mode

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

Indicate that we are leaving text entry mode and returning to navigation mode. Here in the base class this does nothing.

Specified by:

exit_text_entry_mode in interface navigable

Parameters:

event - evt the event causing this input

Object - user_info information supplied at focus time

Returns:

boolean indicating whether input was accepted

perform_action

public boolean perform_action(int act_num,
                              event evt,
                              java.lang.Object user_info)

Do an associated with the interactor at the current location. What this means depends on the subject object. Actions out of range for the subject are rejected. Here in the base class this always fails (returns false).

Specified by:

perform_action in interface navigable

Parameters:

int - act_num number of the action to perform

event - evt the event causing this input

Object - user_info information supplied at focus time

Returns:

boolean indicating if the (inputs corresponding to the) action was accepted by the object.

hit_top

public void hit_top()

Provide feedback for attempting to move up past the root. This is normally called internally as a side effect of navigation input calls. Here in the base class this does nothing.

hit_bottom

public void hit_bottom()

Provide feedback for attempting to move down past a leaf. This is normally called internally as a side effect of navigation input calls. Here in the base class this does nothing.

hit_left

public void hit_left()

Provide feedback for attempting to move left past the first sibling. This is normally called internally as a side effect of navigation input calls. Here in the base class this does nothing.

hit_right

public void hit_right()

Provide feedback for attempting to move right past the last sibling. This is normally called internally as a side effect of navigation input calls. Here in the base class this does nothing.

preview_hit_top

public void preview_hit_top()

Provide preview feedback for attempting to move up past the root. This is normally called internally as a side effect of preview input calls. Here in the base class this does nothing.

preview_hit_bottom

public void preview_hit_bottom()

Provide preview feedback for attempting to move down past a leaf. This is normally called internally as a side effect of preview input calls. Here in the base class this does nothing.

preview_hit_left

public void preview_hit_left()

Provide preview feedback for attempting to move left past the first sibling. This is normally called internally as a side effect of preview input calls. Here in the base class this does nothing.

preview_hit_right

public void preview_hit_right()

Provide preview feedback for attempting to move right past the last sibling. This is normally called internally as a side effect of preview input calls. Here in the base class this does nothing.

depart

public void depart(interactor from_interactor)

Provide feedback and/or actions associated with leaving a particular interactor node. Here in the base class this does nothing.

Parameters:

interactor - from_interactor

arrive

public void arrive(interactor at_interactor)

Provide feedback and/or actions associated with arriving at a particular interactor node. Here in the base class this does nothing.

Parameters:

interactor - at_interactor

preview_depart

public void preview_depart(interactor from_interactor)

Provide preview feedback associated with leaving a particular interactor node. Here in the base class this does nothing.

Parameters:

interactor - from_interactor

preview_arrive

public void preview_arrive(interactor at_interactor)

Provide preview feedback associated with arriving at a particular interactor node. Here in the base class this does nothing.

Parameters:

interactor - at_interactor

focus_set_enter

public void focus_set_enter(event cause_evt,
                            focus_dispatch_agent of_agent,
                            java.lang.Object user_info)

Method called when we go in the focus set. Here we just ignore this.

Parameters:

event - cause_evt the event that caused the focus.

focus_dispatch_agent - of_agent the agent doing the focus.

Object - user_info uninterpreted information that was given to the agent when the focus was established.

focus_set_exit

public void focus_set_exit(event cause_evt,
                           focus_dispatch_agent of_agent,
                           java.lang.Object user_info)

Method called when we go in the focus set. Here we just ignore this.

Parameters:

event - cause_evt the event that caused this.

focus_dispatch_agent - of_agent the agent doing the this.

Object - user_info uninterpreted information that was given to the agent when the focus was established.