All Packages Class Hierarchy This Package Previous Next Index
Class COM.taligent.widget.MaskedTextField
java.lang.Object
|
+----java.awt.Component
|
+----java.awt.Canvas
|
+----COM.taligent.widget.TextClipboardComponent
|
+----COM.taligent.widget.MaskedTextField
- public class MaskedTextField
- extends TextClipboardComponent
- implements Runnable, FocusListener, KeyListener, MouseListener, MouseMotionListener
This widget allows the programmer to specify a mask that
identifies the allowed text input from the user. Only
input matching the mask will be allowed.
The actual mask characters within the mask string can be
assigned to any number of pre-defined mask characters or
can be defined by the user of the MaskedTextField.
Any other character specified in the mask string will be
entered into the mask as a literal character. Literal
characters are displayed but are not editable by the user.
The following table lists some of the most common uses of
the MaskedTextField:
Description | Mask | Direction |
Allow Invalid | Shift Text | Move Cursor |
Phone Number | "(###) ###-####" |
InputDirection.RIGHT | false | true |
true |
Numeric Entry | "$####.##" |
InputDirection.LEFT | false | true |
false |
- Version:
- l.0
- Author:
- Andy Clark, Taligent Inc.
- See Also:
- MaskCharacter
-
DEFAULT_ALLOW_INVALID
- Default allow invalid input (false).
-
DEFAULT_BLANK_CHAR
- Default blank character (underscore).
-
DEFAULT_INPUT_DIRECTION
- Default input direction (InputDirection.RIGHT).
-
DEFAULT_MASK_CHARS
- Default mask characters.
-
DEFAULT_MOVE_CURSOR
- Default cursor advancement on character input (true).
-
DEFAULT_RETURN_BLANKS
- Default return blank chars with getText (false).
-
DEFAULT_RETURN_LITERALS
- Default return literals with getText (true).
-
DEFAULT_SHIFT_TEXT
- Default shift of text on input and deletion (true).
-
MaskedTextField()
- Default constructor.
-
MaskedTextField(String)
- Constructs a MaskedTextField with the specified mask.
-
MaskedTextField(String, MaskCharacter[])
- Constructs a MaskedTextField with the specified mask and
array of mask characters.
-
addActionListener(ActionListener)
- Adds an action listener.
-
addMaskedTextFieldListener(MaskedTextFieldListener)
- Adds a masked text field event listener.
-
addTextListener(TextListener)
- Adds a text event listener.
-
copy()
- Copy selection contents to clipboard.
-
cut()
- Copies the selection to the clipboard and sets the
selection to blanks.
-
focusGained(FocusEvent)
- Focus gained.
-
focusLost(FocusEvent)
- Focus lost.
-
getAllowInvalid()
- Returns whether invalid input is allowed.
-
getBlankChar()
- Returns the current character displayed for blank mask
characters.
-
getDisplayText()
- Returns the display text.
-
getEchoChar()
- Returns the echo character used when printing the
text to the screen.
-
getFontMetrics(Font)
- Helper function to return a FontMetrics object.
-
getInputDirection()
- Returns the current input direction.
-
getMask()
- Returns the mask used for input.
-
getMaskCharacters()
- Returns the mask characters allowed in the mask string.
-
getMinimumSize()
- Returns the minimum size of the component.
-
getMoveCursor()
- Returns whether the cursor adjusts its position when
user input is entered.
-
getName()
- Returns the component's current name.
-
getPreferredSize()
- Returns the preferred size of the component.
-
getReturnBlanks()
- Returns true if the text returned from getText() contains
blank characters, false if not.
-
getReturnLiterals()
- Returns true if the text returned from getText() contains
literal characters, false if not.
-
getShiftText()
- Returns whether the text is shifted upon input
or deletion.
-
getText()
- Returns the current text.
-
getText(boolean, boolean)
- Returns the current text with or without the literal
characters and with or without the blank characters.
-
isEchoCharSet()
- Returns true if an echo character has been set.
-
isFocusTraversable()
- This component is focus traversable.
-
keyPressed(KeyEvent)
- A key was pressed.
-
keyReleased(KeyEvent)
-
-
keyTyped(KeyEvent)
- A key was typed.
-
mouseClicked(MouseEvent)
- Mouse clicked in display.
-
mouseDragged(MouseEvent)
- Mouse dragged.
-
mouseEntered(MouseEvent)
-
-
mouseExited(MouseEvent)
-
-
mouseMoved(MouseEvent)
-
-
mousePressed(MouseEvent)
- Move starting point of selection.
-
mouseReleased(MouseEvent)
-
-
paint(Graphics)
- Paints the control.
-
paste()
- Paste clipboard contents.
-
removeActionListener(ActionListener)
- Removes an action listener.
-
removeMaskedTextFieldListener(MaskedTextFieldListener)
- Removes a masked text field event listener.
-
removeTextListener(TextListener)
- Removes a text event listener.
-
run()
- Blink cursor while component has focus.
-
setAllowInvalid(boolean)
- Sets whether invalid input is allowed during user
entry or when text is shifted from its original
position due to entering new text or deleting
existing text.
-
setBlankChar(char)
- Sets the character displayed for blank mask characters.
-
setBounds(int, int, int, int)
- Sets the component bounds.
-
setBounds(Rectangle)
- Sets the component bounds.
-
setEchoChar(char)
- Sets the echo character to use when printing the
text to the screen.
-
setInputDirection(InputDirection)
- Sets the input direction
-
setMask(String)
- Sets the mask string used for input.
-
setMaskCharacters(MaskCharacter[])
- Sets the mask characters allowed in the mask string.
-
setMoveCursor(boolean)
- Sets whether the cursor adjusts its position when
user input is entered.
-
setName(String)
- Sets the component's name.
-
setReturnBlanks(boolean)
- Sets whether the text returned from getText() contains
blank mask characters or not.
-
setReturnLiterals(boolean)
- Sets whether the text returned from getText() contains
literal characters or not.
-
setShiftText(boolean)
- Sets whether the text is shifted upon input or
deletion.
-
setText(String)
- Sets the text of the text field.
-
setText(String, boolean)
- Sets the text of the text field.
-
toString()
- Returns a string representation of this instance.
-
update(Graphics)
- Don't clear area -- not needed.
-
validateText()
- Returns true if the current text is valid, false otherwise.
-
validateText(String)
- Validates the specified string text.
-
validateText(String, boolean)
- Validates the specified string text.
-
validateText(String, boolean, int)
- Validates the specified string text.
DEFAULT_MASK_CHARS
public static final MaskCharacter DEFAULT_MASK_CHARS[]
- Default mask characters. The default uses the
following pre-defined mask characters:
- '#' = digits 0-9, space not allowed
- 'a' = lowercase Roman characters a-z, space not allowed
- 'A' = uppercase Roman characters A-Z, space not allowed
- '@' = alphanumeric characters 0-9a-zA-Z, space not allowed
- See Also:
- DIGITS, LOWERCASE, UPPERCASE, ALPHANUMERIC
DEFAULT_BLANK_CHAR
public static final char DEFAULT_BLANK_CHAR
- Default blank character (underscore).
DEFAULT_INPUT_DIRECTION
public static final InputDirection DEFAULT_INPUT_DIRECTION
- Default input direction (InputDirection.RIGHT).
DEFAULT_SHIFT_TEXT
public static final boolean DEFAULT_SHIFT_TEXT
- Default shift of text on input and deletion (true).
DEFAULT_MOVE_CURSOR
public static final boolean DEFAULT_MOVE_CURSOR
- Default cursor advancement on character input (true).
DEFAULT_ALLOW_INVALID
public static final boolean DEFAULT_ALLOW_INVALID
- Default allow invalid input (false).
DEFAULT_RETURN_LITERALS
public static final boolean DEFAULT_RETURN_LITERALS
- Default return literals with getText (true).
DEFAULT_RETURN_BLANKS
public static final boolean DEFAULT_RETURN_BLANKS
- Default return blank chars with getText (false).
MaskedTextField
public MaskedTextField()
- Default constructor.
MaskedTextField
public MaskedTextField(String mask)
- Constructs a MaskedTextField with the specified mask.
MaskedTextField
public MaskedTextField(String mask,
MaskCharacter masks[])
- Constructs a MaskedTextField with the specified mask and
array of mask characters.
- Parameters:
- mask - The mask string.
- masks - An array of mask characters used in the mask
string.
getFontMetrics
public FontMetrics getFontMetrics(Font font)
- Helper function to return a FontMetrics object. This
method will attempt to get a FontMetrics object from
Toolkit.getFontMetrics(Font) and then from
Graphics.getFontMetrics(Font). If found, the reference
to the FontMetrics is returned. Null is returned if no
valid FontMetrics object is available at the time of
the method call.
- Parameters:
- font - The font whose metrics are requested.
- Overrides:
- getFontMetrics in class Component
run
public void run()
- Blink cursor while component has focus.
focusGained
public void focusGained(FocusEvent evt)
- Focus gained.
focusLost
public void focusLost(FocusEvent evt)
- Focus lost.
isFocusTraversable
public boolean isFocusTraversable()
- This component is focus traversable.
- Overrides:
- isFocusTraversable in class Component
addActionListener
public void addActionListener(ActionListener listener)
- Adds an action listener.
- Parameters:
- listener - The new listener.
- See Also:
- removeActionListener
removeActionListener
public void removeActionListener(ActionListener listener)
- Removes an action listener.
- Parameters:
- listener - The listener to remove.
- See Also:
- addActionListener
addTextListener
public void addTextListener(TextListener listener)
- Adds a text event listener.
- Parameters:
- listener - The new listener.
- Overrides:
- addTextListener in class TextClipboardComponent
- See Also:
- removeTextListener
removeTextListener
public void removeTextListener(TextListener listener)
- Removes a text event listener.
- Parameters:
- listener - The listener to remove.
- Overrides:
- removeTextListener in class TextClipboardComponent
- See Also:
- addTextListener
addMaskedTextFieldListener
public void addMaskedTextFieldListener(MaskedTextFieldListener listener)
- Adds a masked text field event listener.
- Parameters:
- listener - The new listener.
- See Also:
- removeMaskedTextFieldListener
removeMaskedTextFieldListener
public void removeMaskedTextFieldListener(MaskedTextFieldListener listener)
- Removes a masked text field event listener.
- Parameters:
- listener - The listener to remove.
- See Also:
- addMaskedTextFieldListener
setBounds
public void setBounds(Rectangle b)
- Sets the component bounds.
- Overrides:
- setBounds in class Component
setBounds
public void setBounds(int x,
int y,
int w,
int h)
- Sets the component bounds.
- Overrides:
- setBounds in class Component
setName
public void setName(String name)
- Sets the component's name.
- Parameters:
- name - The new name.
- Overrides:
- setName in class Component
- See Also:
- getName
getName
public String getName()
- Returns the component's current name.
- Overrides:
- getName in class Component
- See Also:
- setName
setMask
public synchronized void setMask(String mask)
- Sets the mask string used for input. The actual mask
characters are defined by the current array of
MaskCharacter objects.
Any character that is not defined as a MaskCharacter
is entered as a literal and cannot be changed by the
user. To enter a character literal that would ordinarally
be considered a mask character, "escape" the character
with a preceeding backslash (\).
- Parameters:
- mask - The new mask.
- See Also:
- getMask, setMaskCharacters
getMask
public String getMask()
- Returns the mask used for input.
- See Also:
- setMask
setInputDirection
public synchronized void setInputDirection(InputDirection direction)
- Sets the input direction
- Parameters:
- direction - The new input direction.
- See Also:
- getInputDirection
getInputDirection
public InputDirection getInputDirection()
- Returns the current input direction.
- See Also:
- setInputDirection
setShiftText
public void setShiftText(boolean shift)
- Sets whether the text is shifted upon input or
deletion.
- Parameters:
- shift - True if characters are shifted; false
otherwise.
- See Also:
- getShiftText, DEFAULT_SHIFT_TEXT
getShiftText
public boolean getShiftText()
- Returns whether the text is shifted upon input
or deletion.
- See Also:
- setShiftText
setMoveCursor
public void setMoveCursor(boolean move)
- Sets whether the cursor adjusts its position when
user input is entered.
- Parameters:
- move - True if the cursor moves; false otherwise.
- See Also:
- getMoveCursor, DEFAULT_MOVE_CURSOR
getMoveCursor
public boolean getMoveCursor()
- Returns whether the cursor adjusts its position when
user input is entered.
- See Also:
- setMoveCursor
setAllowInvalid
public void setAllowInvalid(boolean allow)
- Sets whether invalid input is allowed during user
entry or when text is shifted from its original
position due to entering new text or deleting
existing text.
If you register as a MaskedTextFieldListener, you
can be notified when the text becomes invalid and
when the text becomes valid once it is invalid.
You can always check the validity of the entered
text using the following code:
MaskedTextField text = new MaskedTextField();
if (text.validateText()) {
// text is valid
}
- Parameters:
- allow - True to allow invalid, false otherwise.
- See Also:
- getAllowInvalid, DEFAULT_ALLOW_INVALID, addMaskedTextFieldListener
getAllowInvalid
public boolean getAllowInvalid()
- Returns whether invalid input is allowed.
- See Also:
- setAllowInvalid
setMaskCharacters
public synchronized void setMaskCharacters(MaskCharacter maskchars[])
- Sets the mask characters allowed in the mask string.
- Parameters:
- masks - The array of MaskCharacter objects.
- See Also:
- getMaskCharacters, DEFAULT_MASK_CHARS, setMask
getMaskCharacters
public MaskCharacter[] getMaskCharacters()
- Returns the mask characters allowed in the mask string.
- See Also:
- setMaskCharacters
setBlankChar
public void setBlankChar(char ch)
- Sets the character displayed for blank mask characters.
- Parameters:
- ch - The new blank character.
- See Also:
- getBlankChar, DEFAULT_BLANK_CHAR
getBlankChar
public char getBlankChar()
- Returns the current character displayed for blank mask
characters.
- See Also:
- setBlankChar
setReturnLiterals
public void setReturnLiterals(boolean include)
- Sets whether the text returned from getText() contains
literal characters or not.
- Parameters:
- include - True to include literals, false otherwise.
- See Also:
- getReturnLiterals, DEFAULT_RETURN_LITERALS, setReturnBlanks, getText
getReturnLiterals
public boolean getReturnLiterals()
- Returns true if the text returned from getText() contains
literal characters, false if not.
- See Also:
- setReturnLiterals
setReturnBlanks
public void setReturnBlanks(boolean include)
- Sets whether the text returned from getText() contains
blank mask characters or not. If true, the text obtained
from getText() will contain the blank character
displayed on the screen.
- Parameters:
- include - True to include blanks, false otherwise.
- See Also:
- getReturnBlanks, DEFAULT_RETURN_BLANKS, setReturnLiterals, getText
getReturnBlanks
public boolean getReturnBlanks()
- Returns true if the text returned from getText() contains
blank characters, false if not.
- See Also:
- setReturnBlanks
getDisplayText
protected String getDisplayText()
- Returns the display text. This method is not used by
the user of this component. Use getText() instead.
- Overrides:
- getDisplayText in class TextClipboardComponent
validateText
public boolean validateText()
- Returns true if the current text is valid, false otherwise.
validateText
public boolean validateText(String str)
- Validates the specified string text. Returns true if the
specified string matches the mask set, false otherwise.
The string must contain all of the characters, including
literals.
- Parameters:
- str - The string to check.
validateText
public boolean validateText(String str,
boolean all)
- Validates the specified string text. Returns true if the
specified string matches the mask set, false otherwise.
- Parameters:
- str - The string to check.
- all - True if str contains all of the characters
(including literals), false if str contains
only the match characters.
validateText
public boolean validateText(String str,
boolean all,
int index)
- Validates the specified string text. Returns true if the
specified string matches the mask set, false otherwise.
- Parameters:
- str - The string to check.
- all - True if str contains all of the characters
(including literals), false if str contains
only the match characters.
- index - The index into the text where str is trying
to be inserted.
setText
public void setText(String text)
- Sets the text of the text field.
- Parameters:
- text - The new text. Whether or not the supplied
text contains the literal characters or not
is determined by getReturnBlanks() and
getReturnLiterals().
- Overrides:
- setText in class TextClipboardComponent
- See Also:
- getText, getReturnBlanks, getReturnLiterals
setText
public synchronized void setText(String text,
boolean all)
- Sets the text of the text field.
- Parameters:
- text - The new text.
- all - True if new text contains all characters
(including literals); false if new text
only contains mask characters.
getText
public String getText()
- Returns the current text.
- Overrides:
- getText in class TextClipboardComponent
- See Also:
- setText, setReturnBlanks, setReturnLiterals
getText
public synchronized String getText(boolean literals,
boolean blanks)
- Returns the current text with or without the literal
characters and with or without the blank characters.
- Parameters:
- literals - True to return literals, false otherwise.
- blanks - True to return blanks, false otherwise.
setEchoChar
public void setEchoChar(char echo)
- Sets the echo character to use when printing the
text to the screen. This feature is useful when a
password should not be echoed to the screen. To
unset the echo character, use the value
?. This value is defined by The
Unicode
Standard: Version 2.0 as "not used to represent
Unicode characters" (p. 2-13).
- Parameters:
- echo - The echo character to use.
- See Also:
- getEchoChar, isEchoCharSet
getEchoChar
public char getEchoChar()
- Returns the echo character used when printing the
text to the screen. The method isEchoCharSet() is
provided as a convenience to check whether the echo
character has been set or not. An unset echo
character has the value of ?.
- See Also:
- setEchoChar, isEchoCharSet
isEchoCharSet
public boolean isEchoCharSet()
- Returns true if an echo character has been set.
- See Also:
- setEchoChar, getEchoChar
getPreferredSize
public Dimension getPreferredSize()
- Returns the preferred size of the component.
- Overrides:
- getPreferredSize in class Component
getMinimumSize
public Dimension getMinimumSize()
- Returns the minimum size of the component.
- Overrides:
- getMinimumSize in class Component
update
public void update(Graphics g)
- Don't clear area -- not needed.
- Overrides:
- update in class Component
paint
public void paint(Graphics graphics)
- Paints the control.
- Overrides:
- paint in class Canvas
keyTyped
public void keyTyped(KeyEvent evt)
- A key was typed.
- Parameters:
- evt - The event that occured.
keyPressed
public void keyPressed(KeyEvent evt)
- A key was pressed.
- Parameters:
- evt - The event that occured.
keyReleased
public void keyReleased(KeyEvent evt)
mouseClicked
public synchronized void mouseClicked(MouseEvent evt)
- Mouse clicked in display.
mousePressed
public synchronized void mousePressed(MouseEvent evt)
- Move starting point of selection.
mouseReleased
public void mouseReleased(MouseEvent evt)
mouseEntered
public void mouseEntered(MouseEvent evt)
mouseExited
public void mouseExited(MouseEvent evt)
mouseDragged
public synchronized void mouseDragged(MouseEvent evt)
- Mouse dragged.
mouseMoved
public void mouseMoved(MouseEvent evt)
toString
public String toString()
- Returns a string representation of this instance.
- Overrides:
- toString in class Component
cut
public synchronized void cut()
- Copies the selection to the clipboard and sets the
selection to blanks.
- Overrides:
- cut in class TextClipboardComponent
copy
public synchronized void copy()
- Copy selection contents to clipboard.
- Overrides:
- copy in class TextClipboardComponent
paste
public synchronized void paste()
- Paste clipboard contents. The paste operation will
fail if the selection length is not equal to the
clipboard text length or if the text on the clipboard
does not match the mask set.
Note: The clipboard contents must contain all
valid characters, including literals, to be valid.
- Overrides:
- paste in class TextClipboardComponent
All Packages Class Hierarchy This Package Previous Next Index