magi.toolkit.fields
Class MagiDateField

java.lang.Object
  |
  +--java.awt.Component
        |
        +--java.awt.Container
              |
              +--javax.swing.JComponent
                    |
                    +--javax.swing.text.JTextComponent
                          |
                          +--javax.swing.JTextField
                                |
                                +--magi.toolkit.fields.MagiTextField
                                      |
                                      +--magi.toolkit.fields.MagiDateField
All Implemented Interfaces:
javax.accessibility.Accessible, java.awt.image.ImageObserver, java.awt.MenuContainer, javax.swing.Scrollable, java.io.Serializable, javax.swing.SwingConstants

public class MagiDateField
extends MagiTextField

A date text field component that masks user input to allow only date specific character input, based on the chosen date format.

Author:
Paul Atkinson, Magi Systems Pty Ltd.
See Also:
Serialized Form

Field Summary
static java.lang.String FORMAT_D_M_YYYY
           
static java.lang.String FORMAT_D_MMM_YY
           
static java.lang.String FORMAT_M_D_YYYY
           
 
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
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class java.awt.Container
 
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
MagiDateField()
          Default constructor.
MagiDateField(java.lang.String text)
          Create a date text field, displaying the supplied text String.
MagiDateField(java.lang.String text, boolean upperCase)
          Create a date text field, displaying the supplied text String.
MagiDateField(java.lang.String text, java.lang.String format, int numChars, boolean upperCase)
          Create a date text field, displaying the supplied text String.
 
Method Summary
 java.lang.String getFormat()
          Returns the current format String for this text field.
 boolean isLowerCase()
          Returns true if date text formatting is lowercase.
 boolean isUpperCase()
          Returns true if date text formatting is uppercase.
 boolean isValid()
          Determine if the text in this field is currently valid, based on the current format.
 boolean isValid(java.lang.String text)
          Determine if the text String passed in is a valid date String, based on the current format.
 void isValidEx(java.lang.String text)
          Determine if the text String passed in is a valid date String, based on the current format.
 boolean isValidMonthString(java.lang.String month)
          Determines if the month String is one of the valid 3 character month Strings, for example JAN, FEB, MAR, etc.
 void setDisplaySize(int numChars)
          Set the display size of this date field, based on the desired number of characters to be visible in the field.
 void setFormat(java.lang.String format)
          Set the date format for this text field.
 void setLowerCase(boolean lowerCase)
          Set any text month portion of this date to lowercase, if relevant.
 void setUpperCase(boolean upperCase)
          Set any text month portion of this date to uppercase, if relevant.
 
Methods inherited from class magi.toolkit.fields.MagiTextField
setPreferredWidth
 
Methods inherited from class javax.swing.JTextField
addActionListener, configurePropertiesFromAction, createActionPropertyChangeListener, createDefaultModel, fireActionPerformed, getAccessibleContext, getAction, getActionListeners, getActions, getColumns, getColumnWidth, getHorizontalAlignment, getHorizontalVisibility, getPreferredSize, getScrollOffset, getUIClassID, isValidateRoot, paramString, postActionEvent, removeActionListener, scrollRectToVisible, setAction, setActionCommand, setColumns, setDocument, setFont, setHorizontalAlignment, setScrollOffset
 
Methods inherited from class javax.swing.text.JTextComponent
addCaretListener, addInputMethodListener, addKeymap, copy, cut, fireCaretUpdate, 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, paste, processInputMethodEvent, read, removeCaretListener, removeKeymap, removeNotify, replaceSelection, select, selectAll, setCaret, setCaretColor, setCaretPosition, setComponentOrientation, setDisabledTextColor, setDragEnabled, setEditable, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setText, 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, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, 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, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, 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, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, 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, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setFocusCycleRoot, setFocusTraversalKeys, setFocusTraversalPolicy, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, 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, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processMouseEvent, processMouseWheelEvent, 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
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

FORMAT_D_MMM_YY

public static final java.lang.String FORMAT_D_MMM_YY
See Also:
Constant Field Values

FORMAT_D_M_YYYY

public static final java.lang.String FORMAT_D_M_YYYY
See Also:
Constant Field Values

FORMAT_M_D_YYYY

public static final java.lang.String FORMAT_M_D_YYYY
See Also:
Constant Field Values
Constructor Detail

MagiDateField

public MagiDateField()
Default constructor.


MagiDateField

public MagiDateField(java.lang.String text)
Create a date text field, displaying the supplied text String. A runtime exception (IllegalArgumentException) will be thrown if the text String is an invalid format.

Parameters:
text - the text to display in this field.
Throws:
java.lang.IllegalArgumentException
See Also:
setFormat(String)

MagiDateField

public MagiDateField(java.lang.String text,
                     boolean upperCase)
Create a date text field, displaying the supplied text String. A runtime exception (IllegalArgumentException) will be thrown if the text String is an invalid format.

Parameters:
text - the text to display in this field.
upperCase - true if this component converts input to uppercase.
Throws:
java.lang.IllegalArgumentException
See Also:
setFormat(String)

MagiDateField

public MagiDateField(java.lang.String text,
                     java.lang.String format,
                     int numChars,
                     boolean upperCase)
Create a date text field, displaying the supplied text String. A runtime exception (IllegalArgumentException) will be thrown if the text String is an invalid format.

Parameters:
text - the text to display in this field.
format - the format String of the date - see setFormat(String) for more details.
numChars - the number of characters to allow for field sizing.
upperCase - true if this component converts input to uppercase.
Throws:
java.lang.IllegalArgumentException
See Also:
setFormat(String)
Method Detail

setDisplaySize

public void setDisplaySize(int numChars)
Set the display size of this date field, based on the desired number of characters to be visible in the field. Note that this can never be exact when dealing with a proportional font.

Parameters:
numChars - the number of characters to display.

setFormat

public void setFormat(java.lang.String format)
Set the date format for this text field. This will restrict user input to the desired format pattern. Currently, only the following sub-set of date format characters are supported:

d - day of month.
M - month of year.
y - year.

Any other characters are considered to be 'special characters' and will match the user input exactly.

Day of month can be "d" or "dd", to specify the minimum number of digits allowed.

Month of year can be "M" or "MM", to specify the minimum number of digits allowed. It can also be "MMM" to specify a three-character month String, for example JAN, FEB, MAR, etc.

Year can be "yy" or "yyyy" to specify the minimum number of digits allowed. If using a four digit year, the first digit must be 1 or 2.

The SimpleDateFormat class in Java has a full explanation of these date format specifiers.

Parameters:
format - a date format String.
See Also:
SimpleDateFormat, getFormat()

getFormat

public java.lang.String getFormat()
Returns the current format String for this text field.

Returns:
a format String.
See Also:
setFormat(String)

setUpperCase

public void setUpperCase(boolean upperCase)
Set any text month portion of this date to uppercase, if relevant.

Parameters:
upperCase - true if uppercase.

isUpperCase

public boolean isUpperCase()
Returns true if date text formatting is uppercase.

Returns:
true if uppercase.

setLowerCase

public void setLowerCase(boolean lowerCase)
Set any text month portion of this date to lowercase, if relevant.

Parameters:
lowerCase - true if lowercase.

isLowerCase

public boolean isLowerCase()
Returns true if date text formatting is lowercase.

Returns:
true if lowercase.

isValidMonthString

public boolean isValidMonthString(java.lang.String month)
Determines if the month String is one of the valid 3 character month Strings, for example JAN, FEB, MAR, etc. The case of the month text is ignored.

Parameters:
month - the month String to test.
Returns:
true if it is valid, and false if not.

isValid

public boolean isValid()
Determine if the text in this field is currently valid, based on the current format.

Overrides:
isValid in class java.awt.Component
Returns:
true if valid, and false if not.

isValid

public boolean isValid(java.lang.String text)
Determine if the text String passed in is a valid date String, based on the current format.

Parameters:
text - the text String to validate.
Returns:
true if valid, and false if not.

isValidEx

public void isValidEx(java.lang.String text)
               throws java.lang.IllegalArgumentException
Determine if the text String passed in is a valid date String, based on the current format. If not valid, this method will "balk" by throwing an IllegalArgumentException. See the balking pattern.

Parameters:
text - the text String to validate.
Returns:
true if valid, and false if not.
Throws:
java.lang.IllegalArgumentException