com.froses.widgets
Class MaskedTextField

java.lang.Object
  extended byjava.awt.Component
      extended byjava.awt.Container
          extended byjavax.swing.JComponent
              extended byjavax.swing.text.JTextComponent
                  extended byjavax.swing.JTextField
                      extended bycom.froses.widgets.BoundJTextField
                          extended bycom.froses.widgets.MaskedTextField
All Implemented Interfaces:
javax.accessibility.Accessible, java.awt.image.ImageObserver, java.awt.MenuContainer, javax.swing.Scrollable, java.io.Serializable, javax.swing.SwingConstants

public class MaskedTextField
extends BoundJTextField
implements java.io.Serializable

Is a masked text field.

The mask characters are:

If we want to use any mask character as a normal character, we need to scape it with a backslash character ("\"). For exemple, an e-mail mask may looks like this: '@@@@@@\@@@@@.@@@@'.

The mask is represented into the field using a padChar. This pad char is showing in the writable positions. By default, the par character is an hyphen ('_') but you can change it.

There are two methods to obtain the field contents. The first one, getData() only returns the concatenated contents of the writable positions. For exemple, if we have a phone mask like '(###) ###-##-##' and we fill the field like that '(999) 555-33-44', getData() will return '999553344'. The second one, getText(), returns the exact field contents. For the latest example, '(999) 555-33-44'.

To assign a value we can use the method setData() passing as parameter the concatenated values of writable positions. Thus, to fill the latest example field with a phone number, we can do setData('999553344'). In any value don't match with the mask an IllegalArgumentException is raised.

The paste operation is disallowed for this field and you must enter only one character at time.

Severak keys has been captured to adapt their behaviour to the mask: To clear the field, we can use the clear() method or assign an empty string to data: setData("").

10/09/2001: Added the new method boolean isEmpty(). Creation date: (08/05/2001 11:23:58)

See Also:
Serialized Form

Nested Class Summary
 
Nested classes inherited from class javax.swing.text.JTextComponent
javax.swing.text.JTextComponent.AccessibleJTextComponent, javax.swing.text.JTextComponent.KeyBinding
 
Nested classes inherited from class javax.swing.JComponent
javax.swing.JComponent.AccessibleJComponent
 
Field Summary
 
Fields inherited from class javax.swing.JTextField
notifyAction
 
Fields inherited from class javax.swing.text.JTextComponent
DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY
 
Fields inherited from class javax.swing.JComponent
TOOL_TIP_TEXT_KEY, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface javax.swing.SwingConstants
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
MaskedTextField()
          Default constructor.
MaskedTextField(javax.swing.text.Document doc, java.lang.String text, int columns)
          MaskedTextField constructor.
MaskedTextField(int columns)
          MaskedTextField constructor.
MaskedTextField(java.lang.String aMask)
          MaskedTextField constructor.
MaskedTextField(java.lang.String text, int columns)
          MaskedTextField constructor.
 
Method Summary
 void clear()
          Clears the field restoring the mask with the padding characters.
 java.lang.String getData()
          Returns the data entered by the user in the Editable portion.
 int getFirstWritablePos()
          Returns the first writable position or -1 if no writable positions are available.
 int getLastWritablePos()
          Returns the last writable position or -1 if no writable positions are available.
 java.lang.String getMask()
          Returns the Mask used in this Masked Text Field Component.
 char getPadChar()
          Returns the paddin character (the character used to display the writable positions).
 boolean isEmpty()
          Determines if the field is empty removing the padChars.
 void paste()
          Overrides paste() method to avoid pastes.
 void setData(java.lang.String data)
          Sets the editable portion of this Masked Text Field component with the specified data.
 void setMask(java.lang.String mask)
          Sets the mask value.
 void setPadChar(char padChar)
          Sets the padChar value.
 void setText(java.lang.String text)
          Sets the data for the editable portion of the MaskedTextField.
 
Methods inherited from class javax.swing.JTextField
addActionListener, getAccessibleContext, getAction, getActionListeners, getActions, getColumns, getHorizontalAlignment, getHorizontalVisibility, getPreferredSize, getScrollOffset, getUIClassID, isValidateRoot, postActionEvent, removeActionListener, scrollRectToVisible, setAction, setActionCommand, setColumns, setDocument, setFont, setHorizontalAlignment, setScrollOffset
 
Methods inherited from class javax.swing.text.JTextComponent
addCaretListener, addInputMethodListener, addKeymap, copy, cut, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getNavigationFilter, getPreferredScrollableViewportSize, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getText, getToolTipText, getUI, isEditable, loadKeymap, modelToView, moveCaretPosition, read, removeCaretListener, removeKeymap, removeNotify, replaceSelection, select, selectAll, setCaret, setCaretColor, setCaretPosition, setComponentOrientation, setDisabledTextColor, setDragEnabled, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setUI, updateUI, viewToModel, write
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getGraphics, getHeight, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPropertyChangeListeners, getPropertyChangeListeners, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isMaximumSizeSet, isMinimumSizeSet, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isPreferredSizeSet, isRequestFocusEnabled, paint, paintImmediately, paintImmediately, print, printAll, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setForeground, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, remove, remove, removeAll, removeContainerListener, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setLayout, transferFocusBackward, transferFocusDownCycle, validate
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, contains, createImage, createImage, createVolatileImage, createVolatileImage, dispatchEvent, enable, enableInputMethods, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

MaskedTextField

public MaskedTextField()
Default constructor.


MaskedTextField

public MaskedTextField(int columns)
MaskedTextField constructor.

Parameters:
columns - int

MaskedTextField

public MaskedTextField(java.lang.String aMask)
MaskedTextField constructor.


MaskedTextField

public MaskedTextField(java.lang.String text,
                       int columns)
MaskedTextField constructor.

Parameters:
text - java.lang.String
columns - int

MaskedTextField

public MaskedTextField(javax.swing.text.Document doc,
                       java.lang.String text,
                       int columns)
MaskedTextField constructor.

Parameters:
doc - javax.swing.text.Document
text - java.lang.String
columns - int
Method Detail

clear

public void clear()

Clears the field restoring the mask with the padding characters.

Creation date: (3/6/01 18:22:22)


getData

public java.lang.String getData()

Returns the data entered by the user in the Editable portion.

If there are positions filled with the pad char, the pad char is returned in this positions.

Returns:
The data value.
See Also:
setData(java.lang.String)

getFirstWritablePos

public int getFirstWritablePos()

Returns the first writable position or -1 if no writable positions are available.

Creation date: (09/05/2001 16:05:27)

Returns:
int

getLastWritablePos

public int getLastWritablePos()

Returns the last writable position or -1 if no writable positions are available.

Creation date: (09/05/2001 15:59:30)

Returns:
int

getMask

public java.lang.String getMask()

Returns the Mask used in this Masked Text Field Component.

Returns:
The mask value.
See Also:
setMask(java.lang.String)

getPadChar

public char getPadChar()

Returns the paddin character (the character used to display the writable positions).

Returns:
The padChar value.
See Also:
setPadChar(char)

isEmpty

public boolean isEmpty()

Determines if the field is empty removing the padChars.

Returns:
boolean

paste

public void paste()

Overrides paste() method to avoid pastes.


setData

public void setData(java.lang.String data)

Sets the editable portion of this Masked Text Field component with the specified data.

Throws an IllegalArgumentException when the parameter is null or when the data length is wrong, except if data is a zero length string. In this case, we clear the field.

Parameters:
data - new data value.
See Also:
getData()

setMask

public void setMask(java.lang.String mask)

Sets the mask value. Builds the template and assigns it as text.

Parameters:
mask - The new mask value.
See Also:
getMask()

setPadChar

public void setPadChar(char padChar)

Sets the padChar value.

Parameters:
padChar - The new padChar value.
See Also:
getPadChar()

setText

public void setText(java.lang.String text)

Sets the data for the editable portion of the MaskedTextField.

Parameters:
text - java.lang.String