|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjava.awt.Component
org.havi.ui.HComponent
org.havi.ui.HVisible
org.havi.ui.HSinglelineEntry
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.
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 . |
Field Summary |
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 | |
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(java.lang.String text,
int maxChars,
java.awt.Font font,
java.awt.Color color)
Creates an HSinglelineEntry
object. |
|
HSinglelineEntry(java.lang.String text,
int x,
int y,
int width,
int height,
int maxChars,
java.awt.Font font,
java.awt.Color color)
Creates an HSinglelineEntry
object. |
Method Summary | |
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. if the echo character is non-zero. |
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. |
java.lang.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. when the HNavigable receives a
HFocusEvent event of type
FOCUS_GAINED . |
void |
setLook(HLook hlook)
Sets the HLook for this component. |
void |
setLoseFocusSound(HSound sound)
Associate a sound with losing focus, i.e. when the HNavigable receives a
HFocusEvent event of type
FOCUS_LOST. |
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(java.lang.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. when the input type is set to HKeyboardInputPreferred.INPUT_CUSTOMIZED . |
Methods inherited from class org.havi.ui.HComponent |
getMatte, isDoubleBuffered, isEnabled, processEvent, setMatte |
Methods inherited from class java.awt.Component |
addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addNotify, addPropertyChangeListener, areFocusTraversalKeysSet, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, doLayout, enableEvents, enableInputMethods, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getCursor, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHeight, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getWidth, getX, getY, hasFocus, imageUpdate, invalidate, isBackgroundSet, isCursorSet, isDisplayable, isFocusable, isFocusCycleRoot, isFocusOwner, isFontSet, isForegroundSet, isLightweight, isShowing, isValid, isVisible, list, list, list, list, list, paintAll, paramString, prepareImage, prepareImage, print, printAll, processComponentEvent, processFocusEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removeNotify, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, setBackground, setBounds, setBounds, setCursor, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, setVisible, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, validate |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Constructor Detail |
public HSinglelineEntry()
HSinglelineEntry
object. See the class description for details
of constructor parameters and default values.
public HSinglelineEntry(java.lang.String text, int x, int y, int width, int height, int maxChars, java.awt.Font font, java.awt.Color color)
HSinglelineEntry
object. See the class description for details
of constructor parameters and default values.
public HSinglelineEntry(int x, int y, int width, int height, int maxChars)
HSinglelineEntry
object. See the class description for details
of constructor parameters and default values.
public HSinglelineEntry(java.lang.String text, int maxChars, java.awt.Font font, java.awt.Color color)
HSinglelineEntry
object. See the class description for details
of constructor parameters and default values.
public HSinglelineEntry(int maxChars)
HSinglelineEntry
object. See the class description for details
of constructor parameters and default values.
Method Detail |
public void setTextContent(java.lang.String string, int state)
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.
setTextContent
in class HVisible
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
.getTextContent(int)
public java.lang.String getTextContent(int state)
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.
getTextContent
in class HVisible
state
- The state of the component for which this content
should be displayed. This parameter shall be ignored.
HSinglelineEntry
setTextContent(java.lang.String, int)
public int getCaretCharPosition()
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
public int setCaretCharPosition(int position)
position
- the new position of the text insertion caret.
public void setType(int type)
type
- sum of one or several of HKeyboardInputPreferred.INPUT_ANY
,
HKeyboardInputPreferred.INPUT_NUMERIC
, HKeyboardInputPreferred.INPUT_ALPHA
or
HKeyboardInputPreferred.INPUT_CUSTOMIZED
.public void setValidInput(char[] inputChars)
HKeyboardInputPreferred.INPUT_CUSTOMIZED
.
inputChars
- an array of characters which comprises the
valid input characters.public boolean echoCharIsSet()
public char getEchoChar()
public void setEchoChar(char c)
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.public static void setDefaultLook(HSinglelineEntryLook look)
HLook
for further
HSinglelineEntry
Components.
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.public static HSinglelineEntryLook getDefaultLook()
HLook
for HSinglelineEntry
components.
HLook
that is used by
default when creating a new HSinglelineEntry
component.public void setLook(HLook hlook) throws HInvalidLookException
HLook
for this component.
setLook
in class HVisible
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.
HInvalidLookException
- If the Look is not an HSinglelineEntryLook
.public boolean insertChar(char c)
c
- the character to insert
public boolean deletePreviousChar()
public boolean deleteNextChar()
public void caretNextCharacter()
getCaretCharPosition()
method.
public void caretPreviousCharacter()
getCaretCharPosition()
method.
public void setMaxChars(int maxChars)
maxChars
- - the maximum number of characters.public int getMaxChars()
public void setMove(int keyCode, HNavigable target)
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.
setMove
in interface HNavigable
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.public HNavigable getMove(int keyCode)
HNavigable
object
that is navigated to when a particular key is pressed.
getMove
in interface HNavigable
keyCode
- The key code of the pressed key.
HNavigable
object or null
if no HNavigable
is associated with the keyCode.public void setFocusTraversal(HNavigable up, HNavigable down, HNavigable left, HNavigable right)
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.
setFocusTraversal
in interface HNavigable
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.public boolean isSelected()
isSelected
in interface HNavigable
true
if the component has focus, otherwise
returns false
.public void setGainFocusSound(HSound sound)
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.
setGainFocusSound
in interface HNavigable
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
.public void setLoseFocusSound(HSound sound)
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.
setLoseFocusSound
in interface HNavigable
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
.public HSound getGainFocusSound()
getGainFocusSound
in interface HNavigable
public HSound getLoseFocusSound()
getLoseFocusSound
in interface HNavigable
public void addHFocusListener(HFocusListener l)
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.
addHFocusListener
in interface HNavigable
l
- the HFocusListener to addpublic void removeHFocusListener(HFocusListener l)
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.
removeHFocusListener
in interface HNavigable
l
- the HFocusListener to removepublic int[] getNavigationKeys()
getNavigationKeys
in interface HNavigationInputPreferred
null
if no
navigation targets are set on this component.public void processHFocusEvent(HFocusEvent evt)
HFocusEvent
sent to this HSinglelineEntry
.
processHFocusEvent
in interface HNavigationInputPreferred
evt
- the HFocusEvent
to process.public void addHKeyListener(HKeyListener l)
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.
addHKeyListener
in interface HTextValue
l
- the HKeyListener to addpublic void removeHKeyListener(HKeyListener l)
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.
removeHKeyListener
in interface HTextValue
l
- the HKeyListener to removepublic void addHTextListener(HTextListener l)
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.
addHTextListener
in interface HTextValue
l
- the HTextListener to addpublic void removeHTextListener(HTextListener l)
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.
removeHTextListener
in interface HTextValue
l
- the HTextListener to removepublic boolean getEditMode()
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.
getEditMode
in interface HKeyboardInputPreferred
true
if this component is in edit mode,
false
otherwise.public void setEditMode(boolean edit)
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.
setEditMode
in interface HKeyboardInputPreferred
edit
- true to switch this component into edit mode, false
otherwise.HKeyboardInputPreferred.getEditMode()
public int getType()
getType
in interface HKeyboardInputPreferred
HKeyboardInputPreferred.INPUT_ANY
,
HKeyboardInputPreferred.INPUT_NUMERIC
,
HKeyboardInputPreferred.INPUT_ALPHA
,
or HKeyboardInputPreferred.INPUT_CUSTOMIZED
.public char[] getValidInput()
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.
getValidInput
in interface HKeyboardInputPreferred
null
.public void processHTextEvent(HTextEvent evt)
HTextEvent
sent to this HSinglelineEntry
.
processHTextEvent
in interface HKeyboardInputPreferred
evt
- the HTextEvent
to process.public void processHKeyEvent(HKeyEvent evt)
HKeyEvent
sent to this HSinglelineEntry
.
processHKeyEvent
in interface HKeyboardInputPreferred
evt
- the HKeyEvent
to process.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |