sub_arctic.new_lib
Interface audio_navigation_aware

All Known Implementing Classes:

generic_audio_xlation

public abstract interface audio_navigation_aware

This interface provides an API for objects that are aware of audio navigation and wish to provide specialized behavior.

Method Summary

audio_renderer	audio_rendition() Audio rendition for the object -- this portrays the type of the object as well as possibly its content.
boolean	display_this() Ask the object whether an audio navigation should attempt to display this object, or should consider it a purely visual element and ignore it.
void	enter_action() Perform any special action that needs to be done when navigation arrives at this object.
void	exit_action() Perform any special action that needs to be done when navigation departs from this object.
int	num_actions() Indicate how many actions this object supports.
audio_renderer	perform_action(int act_num, event evt_cause, java.lang.Object user_info) Perform an action associated with this object.
audio_renderer	start_feedback_for(int act_num) Return an object describing audio feedback for the start of a particular action.
boolean	stop_here() Ask the object whether an audio navigation should pause here to wait for the user, or continue to the next navigation position.

Method Detail

display_this

public boolean display_this()

Ask the object whether an audio navigation should attempt to display this object, or should consider it a purely visual element and ignore it.

Returns:

boolean indicating if display should be attempted.

stop_here

public boolean stop_here()

Ask the object whether an audio navigation should pause here to wait for the user, or continue to the next navigation position. By current convention, all navigations stop at each displayable object (so this would always return true). This is primarily here as a hook for potential changes later.

Returns:

boolean indicating whether the navigation should stop here.

audio_rendition

public audio_renderer audio_rendition()

Audio rendition for the object -- this portrays the type of the object as well as possibly its content. Later when we have a decent audio API, we will split this into an parts (such as icon and content) and concatenate them, but for now we lump it all together since we have no ability to concatenate audio.

Returns:

audio_renderer a description of the audio produce for this object

enter_action

public void enter_action()

Perform any special action that needs to be done when navigation arrives at this object.

exit_action

public void exit_action()

Perform any special action that needs to be done when navigation departs from this object.

num_actions

public int num_actions()

Indicate how many actions this object supports. Action numbers are indexed starting at 0, so if this returns 2, action numbers 0, and 1 are valid. Only actions 0 to 3 are supported by the navigation input protocol, so normally at most 4 different actions would be supported. Most objects will support only a primary action or no action at all.

Returns:

int the number of different actions that are available with this object.

start_feedback_for

public audio_renderer start_feedback_for(int act_num)

Return an object describing audio feedback for the start of a particular action. Actions which should provide no start feedback can return null. The sound started here will be explicitly stopped when the action completes (i.e., perform_action() returns).

Parameters:

int - act_num number of the action in question.

Returns:

audio_renderer a description of the audio feedback to be associated with the start of the given action.

perform_action

public audio_renderer perform_action(int act_num,
                                     event evt_cause,
                                     java.lang.Object user_info)

Perform an action associated with this object. Actions outside the set supported by this object are ignored. Return from this routine will also signify that its time to stop any start of action feedback (returned by start_feedback_for()).

Parameters:

int - act_num the index of the action to be performed

event - evt_cause the event causing the action to be carried out.

Object - user_info the uninterpreted user_info that came with this input

Returns:

audio_renderer feedback audio that should be given when the action completes. This may be null to indicate no completion feedback.