org.havi.ui

Class HSinglelineEntry

java.lang.Object

java.awt.Component

org.havi.ui.HComponent

org.havi.ui.HVisible

org.havi.ui.HSinglelineEntry

All Implemented Interfaces:

ImageObserver, MenuContainer, Serializable, TestOpacity, HKeyboardInputPreferred, HMatteLayer, HNavigable, HNavigationInputPreferred, HState, HTextValue

Direct Known Subclasses:

HMultilineEntry

public class HSinglelineEntry
extends HVisible
implements HTextValue

The HSinglelineEntry is a user interface component used to receive a single line of alphanumeric entry from the user and can also be used for password input.

Upon creation the HSinglelineEntry is set to a non-editable mode identical in functionality to an HText.

On keyboard-based systems, if the user navigates to the component using the keyboard then the component must first be switched into edit mode before it will accept any key presses (other than for navigation to another component). The mechanism by which the component is switched into and out of edit mode is via HTextEvent events with ids HTextEvent.TEXT_START_CHANGE and HTextEvent.TEXT_END_CHANGE, which may be triggered in response to a key stroke or other Java AWT event.

On entering its editable mode the component will send an HTextEvent event with an id of HTextEvent.TEXT_START_CHANGE to all registered HTextListener listeners. The HSinglelineEntry will then respond to key events by inserting characters into the text string or positioning the insertion point (caret) via further HTextEvent events.

For example, on platforms which do not provide a means of positioning the caret independently from navigating to components, the navigation keys will be interpreted as caret positioning keys in this mode.

While in the editing mode, the component will generate an HTextEvent event with an id of HTextEvent.TEXT_CHANGE whenever the text content of the HSinglelineEntry changes (e.g. a character is inserted).

On receiving an HTextEvent event with an id of HTextEvent.TEXT_END_CHANGE the component shall leave its editable mode and send an HTextEvent event with an id of HTextEvent.TEXT_END_CHANGE to all registered HTextListener listeners. The user can then navigate out of the HSinglelineEntry.

On mouse-based systems, if the user selects the component by clicking a mouse button inside its bounds then the HSinglelineEntry will automatically switch into edit mode and generate an HTextEvent with an id of HTextEvent.TEXT_START_CHANGE. It will stay in edit mode so long as the mouse pointer remains within the bounds of the component. Once the mouse pointer leaves the bounds then it will switch back into non-editable mode and generate an HTextEvent with an id of HTextEvent.TEXT_END_CHANGE.

By default HSinglelineEntry uses the HSinglelineEntryLook to render itself.

The parameters to the constructors are as follows, in cases where parameters are not used, then the constructor should use the default values.

Default parameter values exposed in the constructors

Parameter	Description	Default value	Set method	Get method
x	x-coordinate of top left hand corner of this component in pixels, relative to its parent container (subject to layout management).	---	java.awt.Component#setBounds	java.awt.Component#getBounds
y	y-coordinate of top left hand corner of this component in pixels, relative to its parent container (subject to layout management).	---	java.awt.Component#setBounds	java.awt.Component#getBounds
width	width of this component in pixels (subject to layout management).	---	java.awt.Component#setBounds	java.awt.Component#getBounds
height	height of this component in pixels (subject to layout management).	---	java.awt.Component#setBounds	java.awt.Component#getBounds
text	The text within this HSinglelineEntry, to be used as the displayed and editable content for all states.	null	HVisible.setTextContent(java.lang.String, int)	HVisible.getTextContent(int)
maxChars	The maximum number of characters allowed in this HSinglelineEntry.	16 characters	setMaxChars(int)	getMaxChars()
font	The font to be used for this component.	---	java.awt.Component#setFont.	java.awt.Component#getFont.
color	The color to be used for this component.	---	java.awt.Component#setForeground.	java.awt.Component#getForeground.

Default parameter values not exposed in the constructors

Description	Default value	Set method	Get method
Associated matte (HMatte).	none (i.e. getMatte() returns null)	setMatte	getMatte
The text layout manager responsible for text formatting.	An HDefaultTextLayoutManager object.	HVisible.setTextLayoutManager(org.havi.ui.HTextLayoutManager)	HVisible.getTextLayoutManager()
The background painting mode	HVisible.NO_BACKGROUND_FILL	HVisible.setBackgroundMode(int)	HVisible.getBackgroundMode()
The default preferred size	not set (i.e. NO_DEFAULT_SIZE) unless specified by width and height parameters	HVisible.setDefaultSize(java.awt.Dimension)	HVisible.getDefaultSize()
The horizontal content alignment	HVisible.HALIGN_CENTER	HVisible.setHorizontalAlignment(int)	HVisible.getHorizontalAlignment()
The vertical content alignment	HVisible.VALIGN_CENTER	HVisible.setVerticalAlignment(int)	HVisible.getVerticalAlignment()
The content scaling mode	HVisible.RESIZE_NONE	HVisible.setResizeMode(int)	HVisible.getResizeMode()
The border mode	true	HVisible.setBordersEnabled(boolean)	HVisible.getBordersEnabled()
Caret position	At the end of the current text string	setCaretCharPosition(int)	getCaretCharPosition()
Input type	HKeyboardInputPreferred.INPUT_ANY	setType(int)	getType()
Customized input range	null	setValidInput(char[])	getValidInput()
Password protection (the echo character)	Zero (ASCII NUL), i.e. not password protected.	setEchoChar(char)	getEchoChar() and echoCharIsSet()
The default "look" for this class.	A platform specific HSinglelineEntryLook	HSinglelineEntry.setDefaultLook	HSinglelineEntry.getDefaultLook
The "look" for this object.	The HSinglelineEntryLook returned from HSinglelineEntry.getDefaultLook when this object was created.	HSinglelineEntry.setLook	HSinglelineEntry.getLook
The gain focus sound.	null	setGainFocusSound	getGainFocusSound
The lose focus sound.	null	setLoseFocusSound	getLoseFocusSound

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

Fields inherited from class org.havi.ui.HVisible

ADJUSTMENT_VALUE_CHANGE, ANIMATE_CONTENT_CHANGE, ANIMATION_POSITION_CHANGE, BACKGROUND_FILL, BORDER_CHANGE, CARET_POSITION_CHANGE, CONTENT_CHANGE, ECHO_CHAR_CHANGE, EDIT_MODE_CHANGE, FIRST_CHANGE, GRAPHIC_CONTENT_CHANGE, HALIGN_CENTER, HALIGN_JUSTIFY, HALIGN_LEFT, HALIGN_RIGHT, ITEM_VALUE_CHANGE, LAST_CHANGE, LIST_CONTENT_CHANGE, LIST_ICONSIZE_CHANGE, LIST_LABELSIZE_CHANGE, LIST_MULTISELECTION_CHANGE, LIST_SCROLLPOSITION_CHANGE, LIST_SELECTION_CHANGE, MIN_MAX_CHANGE, NO_BACKGROUND_FILL, NO_DEFAULT_HEIGHT, NO_DEFAULT_SIZE, NO_DEFAULT_WIDTH, ORIENTATION_CHANGE, REPEAT_COUNT_CHANGE, RESIZE_ARBITRARY, RESIZE_NONE, RESIZE_PRESERVE_ASPECT, SIZE_CHANGE, STATE_CHANGE, TEXT_CONTENT_CHANGE, TEXT_VALUE_CHANGE, THUMB_OFFSETS_CHANGE, UNKNOWN_CHANGE, VALIGN_BOTTOM, VALIGN_CENTER, VALIGN_JUSTIFY, VALIGN_TOP

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface org.havi.ui.HKeyboardInputPreferred

INPUT_ALPHA, INPUT_ANY, INPUT_CUSTOMIZED, INPUT_NUMERIC

Fields inherited from interface org.havi.ui.HState

ACTIONED_FOCUSED_STATE, ACTIONED_STATE, ACTIONED_STATE_BIT, ALL_STATES, DISABLED_ACTIONED_FOCUSED_STATE, DISABLED_ACTIONED_STATE, DISABLED_FOCUSED_STATE, DISABLED_STATE, DISABLED_STATE_BIT, FIRST_STATE, FOCUSED_STATE, FOCUSED_STATE_BIT, LAST_STATE, NORMAL_STATE

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Constructors

Constructor and Description
HSinglelineEntry() Creates an HSinglelineEntry object.
HSinglelineEntry(int maxChars) Creates an HSinglelineEntry object.
HSinglelineEntry(int x, int y, int width, int height, int maxChars) Creates an HSinglelineEntry object.
HSinglelineEntry(String text, int maxChars, Font font, Color color) Creates an HSinglelineEntry object.
HSinglelineEntry(String text, int x, int y, int width, int height, int maxChars, Font font, Color color) Creates an HSinglelineEntry object.

Method Summary

Methods

Modifier and Type	Method and Description
void	addHFocusListener(HFocusListener l) Adds the specified HFocusListener to receive HFocusEvent events sent from this HNavigable: If the listener has already been added further calls will add further references to the listener, which will then receive multiple copies of a single event.
void	addHKeyListener(HKeyListener l) Adds the specified HKeyListener to receive HKeyEvent events sent from this HTextValue: If the listener has already been added further calls will add further references to the listener, which will then receive multiple copies of a single event.
void	addHTextListener(HTextListener l) Adds the specified HTextListener to receive HTextEvent events sent from this HTextValue: If the listener has already been added further calls will add further references to the listener, which will then receive multiple copies of a single event.
void	caretNextCharacter() Move the caret to the next character.
void	caretPreviousCharacter() Move the caret to the previous character.
boolean	deleteNextChar() Delete a character forward of the current caret position.
boolean	deletePreviousChar() Delete a character behind the current caret position.
boolean	echoCharIsSet() Determine if this component has an echo character set, i.e.
int	getCaretCharPosition() Gets the position of the text insertion caret for this the current line in this text component.
static HSinglelineEntryLook	getDefaultLook() Returns the currently set default HLook for HSinglelineEntry components.
char	getEchoChar() Returns the character to be used for echoing.
boolean	getEditMode() Get the editing mode for this HSinglelineEntry.
HSound	getGainFocusSound() Get the sound associated with the gain focus event.
HSound	getLoseFocusSound() Get the sound associated with the lost focus event.
int	getMaxChars() Get maximum number of characters.
HNavigable	getMove(int keyCode) Provides the HNavigable object that is navigated to when a particular key is pressed.
int[]	getNavigationKeys() Retrieve the set of key codes which this component maps to navigation targets.
String	getTextContent(int state) Gets the text content used in this HSinglelineEntry.
int	getType() Retrieve the desired input type for this component.
char[]	getValidInput() Retrieve the customized input character range.
boolean	insertChar(char c) Insert a character at the current caret position, subject to the maximum number of input characters.
boolean	isSelected() Indicates if this component has focus.
void	processHFocusEvent(HFocusEvent evt) Process an HFocusEvent sent to this HSinglelineEntry.
void	processHKeyEvent(HKeyEvent evt) Process an HKeyEvent sent to this HSinglelineEntry.
void	processHTextEvent(HTextEvent evt) Process an HTextEvent sent to this HSinglelineEntry.
void	removeHFocusListener(HFocusListener l) Removes the specified HFocusListener so that it no longer receives HFocusEvent events from this HNavigable.
void	removeHKeyListener(HKeyListener l) Removes the specified HKeyListener so that it no longer receives HKeyEvent events from this HTextValue.
void	removeHTextListener(HTextListener l) Removes the specified HTextListener so that it no longer receives HTextEvent events from this HTextValue.
int	setCaretCharPosition(int position) Sets the position of the text insertion caret for this text component.
static void	setDefaultLook(HSinglelineEntryLook look) Sets the default HLook for further HSinglelineEntry Components.
void	setEchoChar(char c) Sets the number of character to echo for this component.
void	setEditMode(boolean edit) Set the editing mode for this HSinglelineEntry.
void	setFocusTraversal(HNavigable up, HNavigable down, HNavigable left, HNavigable right) Set the focus control for an HNavigable component.
void	setGainFocusSound(HSound sound) Associate a sound with gaining focus, i.e.
void	setLook(HLook hlook) Sets the HLook for this component.
void	setLoseFocusSound(HSound sound) Associate a sound with losing focus, i.e.
void	setMaxChars(int maxChars) Set maximum number of characters.
void	setMove(int keyCode, HNavigable target) Defines the navigation path from the current HNavigable to another HNavigable when a particular key is pressed.
void	setTextContent(String string, int state) Sets the text content used in this HSinglelineEntry.
void	setType(int type) Set to indicate to the system which input keys are required by this component.
void	setValidInput(char[] inputChars) Defines the set of the characters which are valid for customized keyboard input, i.e.

Methods inherited from class org.havi.ui.HVisible

getAnimateContent, getBackgroundMode, getBordersEnabled, getContent, getDefaultSize, getGraphicContent, getHorizontalAlignment, getInteractionState, getLook, getLookData, getMaximumSize, getMinimumSize, getPreferredSize, getResizeMode, getTextLayoutManager, getVerticalAlignment, isFocusTraversable, isOpaque, paint, setAnimateContent, setBackgroundMode, setBordersEnabled, setContent, setDefaultSize, setEnabled, setGraphicContent, setHorizontalAlignment, setInteractionState, setLookData, setResizeMode, setTextLayoutManager, setVerticalAlignment, update

Methods inherited from class org.havi.ui.HComponent

getMatte, isDoubleBuffered, isEnabled, processEvent, setMatte

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getAccessibleContext, getAlignmentX, getAlignmentY, getBackground, getBaseline, getBaselineResizeBehavior, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isFocusable, isFocusCycleRoot, isFocusOwner, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, paramString, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, revalidate, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setMaximumSize, setMinimumSize, setName, setPreferredSize, setSize, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, validate

Methods inherited from class java.lang.Object

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

Constructor Detail

HSinglelineEntry

public HSinglelineEntry()

Creates an HSinglelineEntry object. See the class description for details of constructor parameters and default values.

HSinglelineEntry

public HSinglelineEntry(String text,
                int x,
                int y,
                int width,
                int height,
                int maxChars,
                Font font,
                Color color)

Creates an HSinglelineEntry object. See the class description for details of constructor parameters and default values.

HSinglelineEntry

public HSinglelineEntry(int x,
                int y,
                int width,
                int height,
                int maxChars)

Creates an HSinglelineEntry object. See the class description for details of constructor parameters and default values.

HSinglelineEntry

public HSinglelineEntry(String text,
                int maxChars,
                Font font,
                Color color)

Creates an HSinglelineEntry object. See the class description for details of constructor parameters and default values.

HSinglelineEntry

public HSinglelineEntry(int maxChars)

Creates an HSinglelineEntry object. See the class description for details of constructor parameters and default values.

Method Detail

setTextContent

public void setTextContent(String string,
                  int state)

Sets the text content used in this HSinglelineEntry.

Note that HSinglelineEntry components do not support separate pieces of textual content per state (as defined in HState) --- rather a single piece of content is defined for all its interaction states.

Additionally, the setTextContent(java.lang.String, int) method truncates the string according to the current maxChars setting.

Overrides:

setTextContent in class HVisible

Parameters:

string - The content. If the content is null, then any currently assigned content shall be removed for the specified state.

state - The state of the component for which this content should be displayed. This parameter shall be ignored and considered to have the value HState.ALL_STATES.

See Also:

getTextContent(int)

getTextContent

public String getTextContent(int state)

Gets the text content used in this HSinglelineEntry.

Note that HSinglelineEntry components do not support separate pieces of textual content per state (as defined in HState) --- rather a single piece of content is defined for all its interaction states.

Overrides:

getTextContent in class HVisible

Parameters:

state - The state of the component for which this content should be displayed. This parameter shall be ignored.

Returns:

the text content used in this HSinglelineEntry

See Also:

setTextContent(java.lang.String, int)

getCaretCharPosition

public int getCaretCharPosition()

Gets the position of the text insertion caret for this the current line in this text component. The valid values of the caret position are from 0 to the length of the string retrieved using getTextContent, where 0 implies insertion as the first character (i.e. at the start of the string) and (getTextContent()).length() implies that further characters are to be appended onto the end of the string. Hence, the valid caret positions for the string "abc" of length 3, are 0, 1, 2 and 3 --- with caret locations as shown below:

 0 "a" 1 "b" 2 "c" 3
 

Returns:

the position of the text insertion caret.

setCaretCharPosition

public int setCaretCharPosition(int position)

Sets the position of the text insertion caret for this text component. If position is not valid for the current content the caret is moved to the nearest position.

Parameters:

position - the new position of the text insertion caret.

Returns:

the new caret position.

setType

public void setType(int type)

Set to indicate to the system which input keys are required by this component. The input type constants can be added to define the union of the character sets corresponding to the respective constants.

Parameters:

type - sum of one or several of HKeyboardInputPreferred.INPUT_ANY, HKeyboardInputPreferred.INPUT_NUMERIC, HKeyboardInputPreferred.INPUT_ALPHA or HKeyboardInputPreferred.INPUT_CUSTOMIZED.

setValidInput

public void setValidInput(char[] inputChars)

Defines the set of the characters which are valid for customized keyboard input, i.e. when the input type is set to HKeyboardInputPreferred.INPUT_CUSTOMIZED.

Parameters:

inputChars - an array of characters which comprises the valid input characters.

echoCharIsSet

public boolean echoCharIsSet()

Determine if this component has an echo character set, i.e. if the echo character is non-zero.

Returns:

true if an echo character is set, false otherwise.

getEchoChar

public char getEchoChar()

Returns the character to be used for echoing.

Returns:

the character to be used for echoing or 0 (ASCII NUL) if no echo character is set.

setEchoChar

public void setEchoChar(char c)

Sets the number of character to echo for this component.

Parameters:

c - the character used to echo any input, e.g. if c == '*' a password-style input will be displayed. If c is zero (ASCII NUL), then all characters will be echoed on-screen, this is the default behavior.

setDefaultLook

public static void setDefaultLook(HSinglelineEntryLook look)

Sets the default HLook for further HSinglelineEntry Components.

Parameters:

look - The HLook that will be used by default when creating a new HSinglelineEntry component. Note that this parameter may be null, in which case newly created components shall not draw themselves until a non-null look is set using the setLook(org.havi.ui.HLook) method.

getDefaultLook

public static HSinglelineEntryLook getDefaultLook()

Returns the currently set default HLook for HSinglelineEntry components.

Returns:

The HLook that is used by default when creating a new HSinglelineEntry component.

setLook

public void setLook(HLook hlook)
             throws HInvalidLookException

Sets the HLook for this component.

Overrides:

setLook in class HVisible

Parameters:

hlook - The HLook that is to be used for this component. Note that this parameter may be null, in which case the component will not draw itself until a look is set.

Throws:

HInvalidLookException - If the Look is not an HSinglelineEntryLook.

insertChar

public boolean insertChar(char c)

Insert a character at the current caret position, subject to the maximum number of input characters.

Parameters:

c - the character to insert

Returns:

true if the character was inserted, false otherwise.

deletePreviousChar

public boolean deletePreviousChar()

Delete a character behind the current caret position.

Returns:

true if a character was deleted, false otherwise.

deleteNextChar

public boolean deleteNextChar()

Delete a character forward of the current caret position.

Returns:

true if a character was deleted, false otherwise.

caretNextCharacter

public void caretNextCharacter()

Move the caret to the next character. The caret position is constrained such that the insert point lies within the range as defined by the getCaretCharPosition() method.

caretPreviousCharacter

public void caretPreviousCharacter()

Move the caret to the previous character. The caret position is constrained such that the insert point lies within the range as defined by the getCaretCharPosition() method.

setMaxChars

public void setMaxChars(int maxChars)

Set maximum number of characters.

Parameters:

maxChars - - the maximum number of characters.

getMaxChars

public int getMaxChars()

Get maximum number of characters. The behavior of the component when the last character on a line is typed is implementation dependent.

Returns:

the maximum number of characters.

setMove

public void setMove(int keyCode,
           HNavigable target)

Defines the navigation path from the current HNavigable to another HNavigable when a particular key is pressed.

Note that setFocusTraversal is equivalent to multiple calls to setMove, where the key codes VK_UP, VK_DOWN, VK_LEFT, VK_RIGHT are used.

Specified by:

setMove in interface HNavigable

Parameters:

keyCode - The key code of the pressed key. Any numerical keycode is allowed, but the platform may not be able to generate all keycodes. Application authors should only use keys for which HRcCapabilities.isSupported() or HKeyCapabilities.isSupported() returns true.

target - The target HNavigable object that should be navigated to. If a target is to be removed from a particular navigation path, then null shall be specified.

getMove

public HNavigable getMove(int keyCode)

Provides the HNavigable object that is navigated to when a particular key is pressed.

Specified by:

getMove in interface HNavigable

Parameters:

keyCode - The key code of the pressed key.

Returns:

Returns the HNavigable object or null if no HNavigable is associated with the keyCode.

setFocusTraversal

public void setFocusTraversal(HNavigable up,
                     HNavigable down,
                     HNavigable left,
                     HNavigable right)

Set the focus control for an HNavigable component. Note setFocusTraversal is a convenience function for application programmers where a standard up, down, left and right focus traversal between components is required.

Note setFocusTraversal is equivalent to multiple calls to setMove, where the key codes VK_UP, VK_DOWN, VK_LEFT, VK_RIGHT are used.

Note that this API does not prevent the creation of "isolated" HNavigable components --- authors should endeavor to avoid confusing the user.

Specified by:

setFocusTraversal in interface HNavigable

Parameters:

up - The HNavigable component to move to, when the user generates a VK_UP KeyEvent. If there is no HNavigable component to move "up" to, then null shall be specified.

down - The HNavigable component to move to, when the user generates a VK_DOWN KeyEvent. If there is no HNavigable component to move "down" to, then null shall be specified.

left - The HNavigable component to move to, when the user generates a VK_LEFT KeyEvent. If there is no HNavigable component to move "left" to, then null shall be specified.

right - The HNavigable component to move to, when the user generates a VK_RIGHT KeyEvent. If there is no HNavigable component to move "right" to, then null shall be specified.

isSelected

public boolean isSelected()

Indicates if this component has focus.

Specified by:

isSelected in interface HNavigable

Returns:

true if the component has focus, otherwise returns false.

setGainFocusSound

public void setGainFocusSound(HSound sound)

Associate a sound with gaining focus, i.e. when the HNavigable receives a HFocusEvent event of type FOCUS_GAINED. This sound will start to be played when an object implementing this interface gains focus. It is not guaranteed to be played to completion. If the object implementing this interface loses focus before the audio completes playing, the audio will be truncated. Applications wishing to ensure the audio is always played to completion must implement special logic to slow down the focus transitions.

By default, an HNavigable object does not have any gain focus sound associated with it.

Note that the ordering of playing sounds is dependent on the order of the focus lost, gained events.

Specified by:

setGainFocusSound in interface HNavigable

Parameters:

sound - the sound to be played, when the component gains focus. If sound content is already set, the original content is replaced. To remove the sound specify a null HSound.

setLoseFocusSound

public void setLoseFocusSound(HSound sound)

Associate a sound with losing focus, i.e. when the HNavigable receives a HFocusEvent event of type FOCUS_LOST. This sound will start to be played when an object implementing this interface loses focus. It is not guaranteed to be played to completion. It is implementation dependent whether and when this sound will be truncated by any gain focus sound played by the next object to gain focus.

By default, an HNavigable object does not have any lose focus sound associated with it.

Note that the ordering of playing sounds is dependent on the order of the focus lost, gained events.

Specified by:

setLoseFocusSound in interface HNavigable

Parameters:

sound - the sound to be played, when the component loses focus. If sound content is already set, the original content is replaced. To remove the sound specify a null HSound.

getGainFocusSound

public HSound getGainFocusSound()

Get the sound associated with the gain focus event.

Specified by:

getGainFocusSound in interface HNavigable

Returns:

The sound played when the component gains focus. If no sound is associated with gaining focus, then null shall be returned.

getLoseFocusSound

public HSound getLoseFocusSound()

Get the sound associated with the lost focus event.

Specified by:

getLoseFocusSound in interface HNavigable

Returns:

The sound played when the component loses focus. If no sound is associated with losing focus, then null shall be returned.

addHFocusListener

public void addHFocusListener(HFocusListener l)

Adds the specified HFocusListener to receive HFocusEvent events sent from this HNavigable: If the listener has already been added further calls will add further references to the listener, which will then receive multiple copies of a single event.

Specified by:

addHFocusListener in interface HNavigable

Parameters:

l - the HFocusListener to add

removeHFocusListener

public void removeHFocusListener(HFocusListener l)

Removes the specified HFocusListener so that it no longer receives HFocusEvent events from this HNavigable. If the specified listener is not registered, the method has no effect. If multiple references to a single listener have been registered it should be noted that this method will only remove one reference per call.

Specified by:

removeHFocusListener in interface HNavigable

Parameters:

l - the HFocusListener to remove

getNavigationKeys

public int[] getNavigationKeys()

Retrieve the set of key codes which this component maps to navigation targets.

Specified by:

getNavigationKeys in interface HNavigationInputPreferred

Returns:

an array of key codes, or null if no navigation targets are set on this component.

processHFocusEvent

public void processHFocusEvent(HFocusEvent evt)

Process an HFocusEvent sent to this HSinglelineEntry.

Specified by:

processHFocusEvent in interface HNavigationInputPreferred

Parameters:

evt - the HFocusEvent to process.

addHKeyListener

public void addHKeyListener(HKeyListener l)

Adds the specified HKeyListener to receive HKeyEvent events sent from this HTextValue: If the listener has already been added further calls will add further references to the listener, which will then receive multiple copies of a single event.

Specified by:

addHKeyListener in interface HTextValue

Parameters:

l - the HKeyListener to add

removeHKeyListener

public void removeHKeyListener(HKeyListener l)

Removes the specified HKeyListener so that it no longer receives HKeyEvent events from this HTextValue. If the specified listener is not registered, the method has no effect. If multiple references to a single listener have been registered it should be noted that this method will only remove one reference per call.

Specified by:

removeHKeyListener in interface HTextValue

Parameters:

l - the HKeyListener to remove

addHTextListener

public void addHTextListener(HTextListener l)

Adds the specified HTextListener to receive HTextEvent events sent from this HTextValue: If the listener has already been added further calls will add further references to the listener, which will then receive multiple copies of a single event.

Specified by:

addHTextListener in interface HTextValue

Parameters:

l - the HTextListener to add

removeHTextListener

public void removeHTextListener(HTextListener l)

Removes the specified HTextListener so that it no longer receives HTextEvent events from this HTextValue. If the specified listener is not registered, the method has no effect. If multiple references to a single listener have been registered it should be noted that this method will only remove one reference per call.

Specified by:

removeHTextListener in interface HTextValue

Parameters:

l - the HTextListener to remove

getEditMode

public boolean getEditMode()

Get the editing mode for this HSinglelineEntry. If the returned value is true the component is in edit mode, and its textual content may be changed through user interaction such as keyboard events.

The component is switched into and out of edit mode on receiving HTextEvent.TEXT_START_CHANGE and HTextEvent.TEXT_END_CHANGE events.

Specified by:

getEditMode in interface HKeyboardInputPreferred

Returns:

true if this component is in edit mode, false otherwise.

setEditMode

public void setEditMode(boolean edit)

Set the editing mode for this HSinglelineEntry.

This method is provided for the convenience of component implementors. Interoperable applications shall not call this method. It cannot be made protected because interfaces cannot have protected methods.

Specified by:

setEditMode in interface HKeyboardInputPreferred

Parameters:

edit - true to switch this component into edit mode, false otherwise.

See Also:

HKeyboardInputPreferred.getEditMode()

getType

public int getType()

Retrieve the desired input type for this component. This value should be set to indicate to the system which input keys are required by this component. The input type constants can be added to define the union of the character sets corresponding to the respective constants.

Specified by:

getType in interface HKeyboardInputPreferred

Returns:

The sum of one or several of HKeyboardInputPreferred.INPUT_ANY, HKeyboardInputPreferred.INPUT_NUMERIC, HKeyboardInputPreferred.INPUT_ALPHA, or HKeyboardInputPreferred.INPUT_CUSTOMIZED.

getValidInput

public char[] getValidInput()

Retrieve the customized input character range. If getType() returns a value with the INPUT_CUSTOMIZED bit set then this method shall return an array containing the range of customized input keys. If the range of customized input keys has not been set then this method shall return a zero length char array. This method shall return null if getType() returns a value without the INPUT_CUSTOMIZED bit set.

Specified by:

getValidInput in interface HKeyboardInputPreferred

Returns:

an array containing the characters which this component expects the platform to provide, or null.

processHTextEvent

public void processHTextEvent(HTextEvent evt)

Process an HTextEvent sent to this HSinglelineEntry.

Specified by:

processHTextEvent in interface HKeyboardInputPreferred

Parameters:

evt - the HTextEvent to process.

processHKeyEvent

public void processHKeyEvent(HKeyEvent evt)

Process an HKeyEvent sent to this HSinglelineEntry.

Specified by:

processHKeyEvent in interface HKeyboardInputPreferred

Parameters:

evt - the HKeyEvent to process.