sub_arctic.new_lib
Class generic_audio_xlation

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

public class generic_audio_xlation
extends java.lang.Object
implements audio_navigation_aware

This interface provides audio navigation information (implements the audio_navigation_aware interface) for non audio-aware interactors. If this is applied to an audio aware interactor, it simply forwards its methods there. For other interactors it does some detective work to determine properties that can be used for audio rendition (such as whether the object accepts input or produces output such as text that we know how to render in audio)


Field Summary
protected  boolean _accepts_input
          Does this object accept input?
protected  audio_renderer _audio_rendition
          The audio rendition for this object.
protected static audio_renderer _default_audio_rendition
          Default audio rendition for something we can't otherwise figure out.
protected  boolean _display_this
          Do we attempt an audio display of our subject?
protected  boolean _forward_all
          Indication of whether we forward to the subject or work it out on our own.
protected static java.util.Hashtable _known_translations
          Table of known interactor to audio icon translations.
protected  boolean _stop_here
          Do we stop navigation at this object or pass on through?
protected  interactor _subject
          Interactor object we are translating to audio
protected  java.lang.String _text_contents
          The current text contents from this object.
protected  java.lang.String _type_text
          The text string with the type name of this object.
static java.lang.String default_audio_name
          Name portion of the default audio rendition URL -- this will be taken from the document base (for now).
static java.lang.String default_spoken
          Text string to be spoken for default audio rendition.
 
Constructor Summary
generic_audio_xlation(interactor subj)
          Constructor based on a subject interactor.
 
Method Summary
static void add_known_translation(java.lang.String class_name, java.lang.String audio_name)
          Add an entry to the known translations table.
 audio_renderer audio_rendition()
          Audio rendition for the object -- this portrays the type of the object as well as possibly its content.
protected  audio_renderer build_audio_icon(interactor subj)
          Build an audio icon for the given interactor.
protected  java.lang.String build_type_name(interactor subj)
          Create a string to speak for the type of the given object.
static audio_renderer default_audio_rendition()
          Default audio rendition for something we can't otherwise figure out.
 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.
protected  boolean extract_display_material(interactor subj)
          Have a look at the given object and see if we can extract anything that we know how to display via audio.
protected  java.lang.String extract_text(interactor subj)
          Extract any available text from the given object.
protected static void init_known_translations()
          Initialize the table of known interactor to audio icon translations if it hasn't been initialized already.
protected static audio_renderer lookup_icon(java.lang.Class subj_class)
          Try to look up an audio icon for a given interactor class.
 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.
 void set_subject(interactor subj)
          Set the interactor object we are translating to audio
 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.
 interactor subject()
          Interactor object we are translating to audio
 java.lang.String toString()
          Convert to human readable display string for debugging
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

_subject

protected interactor _subject
Interactor object we are translating to audio

_forward_all

protected boolean _forward_all
Indication of whether we forward to the subject or work it out on our own. If this is true, we pass all operations to the subject and the values of most other indicator variables are ignored.

_display_this

protected boolean _display_this
Do we attempt an audio display of our subject?

_stop_here

protected boolean _stop_here
Do we stop navigation at this object or pass on through?

_accepts_input

protected boolean _accepts_input
Does this object accept input?

_audio_rendition

protected audio_renderer _audio_rendition
The audio rendition for this object. This will get filled in with an audio icon and text (by extract_display_material()) before its used.

_text_contents

protected java.lang.String _text_contents
The current text contents from this object. This field is set as a side effect of extract_display_material().

_type_text

protected java.lang.String _type_text
The text string with the type name of this object. This may be the class name, but may have been turned into something closer to speakable English. This field is set as a side effect of extract_display_material().

_known_translations

protected static java.util.Hashtable _known_translations
Table of known interactor to audio icon translations. This is indexed by class objects and contains audio_renderer objects.

default_audio_name

public static final java.lang.String default_audio_name
Name portion of the default audio rendition URL -- this will be taken from the document base (for now).

default_spoken

public static final java.lang.String default_spoken
Text string to be spoken for default audio rendition.

_default_audio_rendition

protected static audio_renderer _default_audio_rendition
Default audio rendition for something we can't otherwise figure out. This will be loaded on demand from the document base using the default name.
Constructor Detail

generic_audio_xlation

public generic_audio_xlation(interactor subj)
Constructor based on a subject interactor.
Parameters:
interactor - subj
Method Detail

subject

public interactor subject()
Interactor object we are translating to audio
Returns:
interactor our subject interactor

set_subject

public void set_subject(interactor subj)
Set the interactor object we are translating to audio
Parameters:
interactor - subj our new subject interactor

toString

public java.lang.String toString()
Convert to human readable display string for debugging
Returns:
String string which displays all our fields for debugging
Overrides:
toString in class java.lang.Object

extract_text

protected java.lang.String extract_text(interactor subj)
Extract any available text from the given object.
Parameters:
interactor - subj the object we extract text.
Returns:
String extracted text with whitespace inserted between extracted text segments. This may be null if there is no text.

build_type_name

protected java.lang.String build_type_name(interactor subj)
Create a string to speak for the type of the given object. This may be the class name, but hopefully we find something a little better, by lookup or manipulation of the string.

Currently we use the class name with underscores turned into spaces Later we should also provide a mechanism for doing special cases via a lookup table and/or aware interactors (and we might insert a space in places where a lower case letter is concatenated with an upper case letter).

Parameters:
interactor - subj the object we are naming
Returns:
String the constructed name text

init_known_translations

protected static void init_known_translations()
Initialize the table of known interactor to audio icon translations if it hasn't been initialized already.

add_known_translation

public static void add_known_translation(java.lang.String class_name,
                                         java.lang.String audio_name)
Add an entry to the known translations table. If this has the same class as an existing entry the old entry is silently replaced.
Parameters:
String - class_name string with the name of the class we are entering a translation for. If there is no class by that name an error is thrown.
String - audio_name name of the audio file (found relative to the document base) to fetch the audio clip from.

lookup_icon

protected static audio_renderer lookup_icon(java.lang.Class subj_class)
Try to look up an audio icon for a given interactor class. If we have stored translation null is returned.

build_audio_icon

protected audio_renderer build_audio_icon(interactor subj)
Build an audio icon for the given interactor. This will first attempt to look up the class of the interactor in a table of known translations. If that fails we will look at the inputs it accepts and the manipulation afforances it draws to make an educated guess (this step is not done yet). If all that fails to turn up something we fallback on a default.
Parameters:
interactor - subj the interactor we are building an icon for
Returns:
audio_renderer sound description (with just the icon part filled in).

extract_display_material

protected boolean extract_display_material(interactor subj)
Have a look at the given object and see if we can extract anything that we know how to display via audio. Note: this sets _text_contents, and _type_text, and _audio_rendition as a side-effect.
Returns:
boolean indicating if something displayable was found

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.
Specified by:
display_this in interface audio_navigation_aware
Returns:
boolean indicating if audio 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.
Specified by:
stop_here in interface audio_navigation_aware
Returns:
boolean indicating whether the navigation should stop here.

default_audio_rendition

public static audio_renderer default_audio_rendition()
Default audio rendition for something we can't otherwise figure out. This will be loaded on demand from the document base using the default name.
Returns:
audio_renderer a description of the default sound

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 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.
Specified by:
audio_rendition in interface audio_navigation_aware
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.
Specified by:
enter_action in interface audio_navigation_aware

exit_action

public void exit_action()
Perform any special action that needs to be done when navigation departs from this object.
Specified by:
exit_action in interface audio_navigation_aware

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.
Specified by:
num_actions in interface audio_navigation_aware
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).
Specified by:
start_feedback_for in interface audio_navigation_aware
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()).
Specified by:
perform_action in interface audio_navigation_aware
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.