sub_arctic.input
Interface text_acceptor

All Known Implementing Classes:
text_edit, oneline_text_edit

public abstract interface text_acceptor
extends focusable

Input protocol for objects that accept textual input. This protocol is dispatched by the text focus agent. In addition to simple text input this protocol provides features for filtering characters, recognizing and acting of special "action characters", and performing standard edit functions (i.e., character delete and line kill).

See Also:
text_focus_agent

Field Summary
static int CLOSURE_ACTION_CHAR
          Constant for return from char_filter to signify that character is to be considered a closure point which ends input and should be acted upon (usually this would be done for end of line characters).
static int DISCARD_CHAR
          Constant for return from char_filter signifying that character is to be discarded.
 
Method Summary
 boolean action_char(event evt, char ch, java.lang.Object user_info)
          Provide input for a character that has been classified as a closure action (by returning CLOSURE_ACTION_CHAR from char_filter).
 int char_filter(int input_char, int modifiers)
          Prefilter a character before providing it as input.
 boolean delete_char(event evt, java.lang.Object user_info)
          Provide input for a character signifying a delete.
 boolean end_text_entry(event evt, java.lang.Object user_info)
          Provide input indicating that text input is over (e.g.
 boolean line_kill(event evt, java.lang.Object user_info)
          Provide input for a character signifying a line kill.
 boolean new_char(event evt, char ch, java.lang.Object user_info)
          Provide input for a single character.
 boolean special_key(event evt, int key_code, java.lang.Object user_info)
          Provide input for a key press signifying a special key (corresponding to KEY_ACTION events).
 boolean start_text_entry(event evt, java.lang.Object user_info)
          indicate that this object is the new text focus and will receive subsequent text input.
 
Methods inherited from interface sub_arctic.input.focusable
focus_set_enter, focus_set_exit
 

Field Detail

DISCARD_CHAR

public static final int DISCARD_CHAR
Constant for return from char_filter signifying that character is to be discarded.

CLOSURE_ACTION_CHAR

public static final int CLOSURE_ACTION_CHAR
Constant for return from char_filter to signify that character is to be considered a closure point which ends input and should be acted upon (usually this would be done for end of line characters).
Method Detail

start_text_entry

public boolean start_text_entry(event evt,
                                java.lang.Object user_info)
indicate that this object is the new text focus and will receive subsequent text input.
Parameters:
event - evt the event that "caused" the start of text input.
Object - user_info the user info associated with this object when it was added to the focus set.

char_filter

public int char_filter(int input_char,
                       int modifiers)
Prefilter a character before providing it as input. This routine gets called to allow the object to modify the character before it is passed to new_char(). Input to the method is the ordinal value of the input character in question along with the modifier mask associated with it. Output should either be the ordinal value of a character or a specific negative value signifying one of several special actions. This routine can be used to do a translation (e.g. to all lower case) or to filter out unwanted characters (e.g. everything except decimal digits).

Filtering is done by returning the special value DISCARD_CHAR (= -1), which signifies that the character is not to be passed to new_char(). Translation is done by returning the ordinal value of the translated character. In addition, the value CLOSURE_ACTION_CHAR (= -2) can be returned to indicate that the action_char() method should be invoked instead of new_char(). This is typically done for end of line characters that signify completion of an entry.

Parameters:
int - input_char ordinal value of the original input character.
int - modifiers modifier mask (see event for encoding).
Returns:
int the ordinal value of the translated character, or one of the special (negative) values DISCARD_CHAR or CLOSURE_ACTION_CHAR.
See Also:
text_focus_agent, event

new_char

public boolean new_char(event evt,
                        char ch,
                        java.lang.Object user_info)
Provide input for a single character.
Parameters:
event - evt the original event for the character input.
char - ch the translated character that should be considered the actual input.
Object - user_info the user info that was associated with this object when it was established as a text focus.

action_char

public boolean action_char(event evt,
                           char ch,
                           java.lang.Object user_info)
Provide input for a character that has been classified as a closure action (by returning CLOSURE_ACTION_CHAR from char_filter).
Parameters:
event - evt the original event for the character input.
char - ch the character.
Object - user_info the user info that was associated with this object when it was established as a text focus.

delete_char

public boolean delete_char(event evt,
                           java.lang.Object user_info)
Provide input for a character signifying a delete. Returns true if the object consumes the input. Currently, by default if either a backspace or a delete character is seen, it will be treated as a delete character. This behavior can be changed via the text input dispatch agent. (Unfortunately, AWT does not currently provide a way to determine the user's edit character preferences, so this is the best we can do.)
Parameters:
event - evt the event for the input.
Object - user_info the user info that was associated with this object when it was established as a text focus.

line_kill

public boolean line_kill(event evt,
                         java.lang.Object user_info)
Provide input for a character signifying a line kill. Returns true if the object consumes the input. Currently a ^U ('\025') is treated as a line kill. This behavior can be changed via the text input dispatch agent. (Unfortunately, AWT does not currently provide a way to determine the user's edit character preferences, so this is the best we can do.)
Parameters:
event - evt the event for the input.
Object - user_info the user info that was associated with this object when it was established as a text focus.

special_key

public boolean special_key(event evt,
                           int key_code,
                           java.lang.Object user_info)
Provide input for a key press signifying a special key (corresponding to KEY_ACTION events). Values passed here are key code values (VK_* values defined in event) Returns true if the object consumes the event.
Parameters:
event - evt the original event for the character input.
int - key_code the key code for the action key (see event).
Object - user_info the user info that was associated with this object when it was established as a text focus.
See Also:
event

end_text_entry

public boolean end_text_entry(event evt,
                              java.lang.Object user_info)
Provide input indicating that text input is over (e.g. the text focus has moved elsewhere.
Parameters:
event - evt the event "causing" this input.
Object - user_info the user info that was associated with this object when it was established as a text focus.