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:
DescriptionMaskDirection Allow InvalidShift TextMove Cursor
Phone Number"(###) ###-####" InputDirection.RIGHTfalsetrue true
Numeric Entry"$####.##" InputDirection.LEFTfalsetrue false

Version:
l.0
Author:
Andy Clark, Taligent Inc.
See Also:
MaskCharacter

Variable Index

 o DEFAULT_ALLOW_INVALID
Default allow invalid input (false).
 o DEFAULT_BLANK_CHAR
Default blank character (underscore).
 o DEFAULT_INPUT_DIRECTION
Default input direction (InputDirection.RIGHT).
 o DEFAULT_MASK_CHARS
Default mask characters.
 o DEFAULT_MOVE_CURSOR
Default cursor advancement on character input (true).
 o DEFAULT_RETURN_BLANKS
Default return blank chars with getText (false).
 o DEFAULT_RETURN_LITERALS
Default return literals with getText (true).
 o DEFAULT_SHIFT_TEXT
Default shift of text on input and deletion (true).

Constructor Index

 o MaskedTextField()
Default constructor.
 o MaskedTextField(String)
Constructs a MaskedTextField with the specified mask.
 o MaskedTextField(String, MaskCharacter[])
Constructs a MaskedTextField with the specified mask and array of mask characters.

Method Index

 o addActionListener(ActionListener)
Adds an action listener.
 o addMaskedTextFieldListener(MaskedTextFieldListener)
Adds a masked text field event listener.
 o addTextListener(TextListener)
Adds a text event listener.
 o copy()
Copy selection contents to clipboard.
 o cut()
Copies the selection to the clipboard and sets the selection to blanks.
 o focusGained(FocusEvent)
Focus gained.
 o focusLost(FocusEvent)
Focus lost.
 o getAllowInvalid()
Returns whether invalid input is allowed.
 o getBlankChar()
Returns the current character displayed for blank mask characters.
 o getDisplayText()
Returns the display text.
 o getEchoChar()
Returns the echo character used when printing the text to the screen.
 o getFontMetrics(Font)
Helper function to return a FontMetrics object.
 o getInputDirection()
Returns the current input direction.
 o getMask()
Returns the mask used for input.
 o getMaskCharacters()
Returns the mask characters allowed in the mask string.
 o getMinimumSize()
Returns the minimum size of the component.
 o getMoveCursor()
Returns whether the cursor adjusts its position when user input is entered.
 o getName()
Returns the component's current name.
 o getPreferredSize()
Returns the preferred size of the component.
 o getReturnBlanks()
Returns true if the text returned from getText() contains blank characters, false if not.
 o getReturnLiterals()
Returns true if the text returned from getText() contains literal characters, false if not.
 o getShiftText()
Returns whether the text is shifted upon input or deletion.
 o getText()
Returns the current text.
 o getText(boolean, boolean)
Returns the current text with or without the literal characters and with or without the blank characters.
 o isEchoCharSet()
Returns true if an echo character has been set.
 o isFocusTraversable()
This component is focus traversable.
 o keyPressed(KeyEvent)
A key was pressed.
 o keyReleased(KeyEvent)
 o keyTyped(KeyEvent)
A key was typed.
 o mouseClicked(MouseEvent)
Mouse clicked in display.
 o mouseDragged(MouseEvent)
Mouse dragged.
 o mouseEntered(MouseEvent)
 o mouseExited(MouseEvent)
 o mouseMoved(MouseEvent)
 o mousePressed(MouseEvent)
Move starting point of selection.
 o mouseReleased(MouseEvent)
 o paint(Graphics)
Paints the control.
 o paste()
Paste clipboard contents.
 o removeActionListener(ActionListener)
Removes an action listener.
 o removeMaskedTextFieldListener(MaskedTextFieldListener)
Removes a masked text field event listener.
 o removeTextListener(TextListener)
Removes a text event listener.
 o run()
Blink cursor while component has focus.
 o 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.
 o setBlankChar(char)
Sets the character displayed for blank mask characters.
 o setBounds(int, int, int, int)
Sets the component bounds.
 o setBounds(Rectangle)
Sets the component bounds.
 o setEchoChar(char)
Sets the echo character to use when printing the text to the screen.
 o setInputDirection(InputDirection)
Sets the input direction
 o setMask(String)
Sets the mask string used for input.
 o setMaskCharacters(MaskCharacter[])
Sets the mask characters allowed in the mask string.
 o setMoveCursor(boolean)
Sets whether the cursor adjusts its position when user input is entered.
 o setName(String)
Sets the component's name.
 o setReturnBlanks(boolean)
Sets whether the text returned from getText() contains blank mask characters or not.
 o setReturnLiterals(boolean)
Sets whether the text returned from getText() contains literal characters or not.
 o setShiftText(boolean)
Sets whether the text is shifted upon input or deletion.
 o setText(String)
Sets the text of the text field.
 o setText(String, boolean)
Sets the text of the text field.
 o toString()
Returns a string representation of this instance.
 o update(Graphics)
Don't clear area -- not needed.
 o validateText()
Returns true if the current text is valid, false otherwise.
 o validateText(String)
Validates the specified string text.
 o validateText(String, boolean)
Validates the specified string text.
 o validateText(String, boolean, int)
Validates the specified string text.

Variables

 o DEFAULT_MASK_CHARS
 public static final MaskCharacter DEFAULT_MASK_CHARS[]
Default mask characters. The default uses the following pre-defined mask characters:

See Also:
DIGITS, LOWERCASE, UPPERCASE, ALPHANUMERIC
 o DEFAULT_BLANK_CHAR
 public static final char DEFAULT_BLANK_CHAR
Default blank character (underscore).

 o DEFAULT_INPUT_DIRECTION
 public static final InputDirection DEFAULT_INPUT_DIRECTION
Default input direction (InputDirection.RIGHT).

 o DEFAULT_SHIFT_TEXT
 public static final boolean DEFAULT_SHIFT_TEXT
Default shift of text on input and deletion (true).

 o DEFAULT_MOVE_CURSOR
 public static final boolean DEFAULT_MOVE_CURSOR
Default cursor advancement on character input (true).

 o DEFAULT_ALLOW_INVALID
 public static final boolean DEFAULT_ALLOW_INVALID
Default allow invalid input (false).

 o DEFAULT_RETURN_LITERALS
 public static final boolean DEFAULT_RETURN_LITERALS
Default return literals with getText (true).

 o DEFAULT_RETURN_BLANKS
 public static final boolean DEFAULT_RETURN_BLANKS
Default return blank chars with getText (false).

Constructors

 o MaskedTextField
 public MaskedTextField()
Default constructor.

 o MaskedTextField
 public MaskedTextField(String mask)
Constructs a MaskedTextField with the specified mask.

 o 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.

Methods

 o 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
 o run
 public void run()
Blink cursor while component has focus.

 o focusGained
 public void focusGained(FocusEvent evt)
Focus gained.

 o focusLost
 public void focusLost(FocusEvent evt)
Focus lost.

 o isFocusTraversable
 public boolean isFocusTraversable()
This component is focus traversable.

Overrides:
isFocusTraversable in class Component
 o addActionListener
 public void addActionListener(ActionListener listener)
Adds an action listener.

Parameters:
listener - The new listener.
See Also:
removeActionListener
 o removeActionListener
 public void removeActionListener(ActionListener listener)
Removes an action listener.

Parameters:
listener - The listener to remove.
See Also:
addActionListener
 o addTextListener
 public void addTextListener(TextListener listener)
Adds a text event listener.

Parameters:
listener - The new listener.
Overrides:
addTextListener in class TextClipboardComponent
See Also:
removeTextListener
 o 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
 o addMaskedTextFieldListener
 public void addMaskedTextFieldListener(MaskedTextFieldListener listener)
Adds a masked text field event listener.

Parameters:
listener - The new listener.
See Also:
removeMaskedTextFieldListener
 o removeMaskedTextFieldListener
 public void removeMaskedTextFieldListener(MaskedTextFieldListener listener)
Removes a masked text field event listener.

Parameters:
listener - The listener to remove.
See Also:
addMaskedTextFieldListener
 o setBounds
 public void setBounds(Rectangle b)
Sets the component bounds.

Overrides:
setBounds in class Component
 o setBounds
 public void setBounds(int x,
                       int y,
                       int w,
                       int h)
Sets the component bounds.

Overrides:
setBounds in class Component
 o setName
 public void setName(String name)
Sets the component's name.

Parameters:
name - The new name.
Overrides:
setName in class Component
See Also:
getName
 o getName
 public String getName()
Returns the component's current name.

Overrides:
getName in class Component
See Also:
setName
 o 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
 o getMask
 public String getMask()
Returns the mask used for input.

See Also:
setMask
 o setInputDirection
 public synchronized void setInputDirection(InputDirection direction)
Sets the input direction

Parameters:
direction - The new input direction.
See Also:
getInputDirection
 o getInputDirection
 public InputDirection getInputDirection()
Returns the current input direction.

See Also:
setInputDirection
 o 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
 o getShiftText
 public boolean getShiftText()
Returns whether the text is shifted upon input or deletion.

See Also:
setShiftText
 o 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
 o getMoveCursor
 public boolean getMoveCursor()
Returns whether the cursor adjusts its position when user input is entered.

See Also:
setMoveCursor
 o 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
 o getAllowInvalid
 public boolean getAllowInvalid()
Returns whether invalid input is allowed.

See Also:
setAllowInvalid
 o 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
 o getMaskCharacters
 public MaskCharacter[] getMaskCharacters()
Returns the mask characters allowed in the mask string.

See Also:
setMaskCharacters
 o 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
 o getBlankChar
 public char getBlankChar()
Returns the current character displayed for blank mask characters.

See Also:
setBlankChar
 o 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
 o getReturnLiterals
 public boolean getReturnLiterals()
Returns true if the text returned from getText() contains literal characters, false if not.

See Also:
setReturnLiterals
 o 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
 o getReturnBlanks
 public boolean getReturnBlanks()
Returns true if the text returned from getText() contains blank characters, false if not.

See Also:
setReturnBlanks
 o 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
 o validateText
 public boolean validateText()
Returns true if the current text is valid, false otherwise.

 o 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.
 o 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.
 o 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.
 o 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
 o 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.
 o getText
 public String getText()
Returns the current text.

Overrides:
getText in class TextClipboardComponent
See Also:
setText, setReturnBlanks, setReturnLiterals
 o 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.
 o 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
 o 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
 o isEchoCharSet
 public boolean isEchoCharSet()
Returns true if an echo character has been set.

See Also:
setEchoChar, getEchoChar
 o getPreferredSize
 public Dimension getPreferredSize()
Returns the preferred size of the component.

Overrides:
getPreferredSize in class Component
 o getMinimumSize
 public Dimension getMinimumSize()
Returns the minimum size of the component.

Overrides:
getMinimumSize in class Component
 o update
 public void update(Graphics g)
Don't clear area -- not needed.

Overrides:
update in class Component
 o paint
 public void paint(Graphics graphics)
Paints the control.

Overrides:
paint in class Canvas
 o keyTyped
 public void keyTyped(KeyEvent evt)
A key was typed.

Parameters:
evt - The event that occured.
 o keyPressed
 public void keyPressed(KeyEvent evt)
A key was pressed.

Parameters:
evt - The event that occured.
 o keyReleased
 public void keyReleased(KeyEvent evt)
 o mouseClicked
 public synchronized void mouseClicked(MouseEvent evt)
Mouse clicked in display.

 o mousePressed
 public synchronized void mousePressed(MouseEvent evt)
Move starting point of selection.

 o mouseReleased
 public void mouseReleased(MouseEvent evt)
 o mouseEntered
 public void mouseEntered(MouseEvent evt)
 o mouseExited
 public void mouseExited(MouseEvent evt)
 o mouseDragged
 public synchronized void mouseDragged(MouseEvent evt)
Mouse dragged.

 o mouseMoved
 public void mouseMoved(MouseEvent evt)
 o toString
 public String toString()
Returns a string representation of this instance.

Overrides:
toString in class Component
 o cut
 public synchronized void cut()
Copies the selection to the clipboard and sets the selection to blanks.

Overrides:
cut in class TextClipboardComponent
 o copy
 public synchronized void copy()
Copy selection contents to clipboard.

Overrides:
copy in class TextClipboardComponent
 o 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