com.izforge.izpack.panels
Class RuleInputField

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by com.izforge.izpack.panels.RuleInputField
All Implemented Interfaces:
ProcessingClient, java.awt.event.FocusListener, java.awt.event.KeyListener, java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable, java.util.EventListener, javax.swing.event.CaretListener

public class RuleInputField
extends javax.swing.JComponent
implements java.awt.event.KeyListener, java.awt.event.FocusListener, javax.swing.event.CaretListener, ProcessingClient

This class assists the user in entering serial numbers.

Serial numbers, license number, CD keys and the like are often lenghty alpha-numerical numbers. In many cases they are devided into multiple parts by dash or point separators. Entering these in a single text field can be a frustrating experience for the user. This class provides a way of presenting the user with an assembly of input fields that are arranged in the same way as the key, with the separators already in place. Immideate testing for format compliance if performed ans soon as each field is completed. In addition, the cursor is automatically advanced to make entering numbers as painless as possible.

Formatting:

Example:

"N:4:4 - H:6:6 - AN:3:3 x A:5:5"

This formatting string will produce a serial number field consisting of four separate input fields. The fisrt input field will accept four numeric digits, the second six hexa-decimal digits, the third three alpha-numeric digits and the fourth five letters. The first three input fields will be separated by '-' and the third and fourth by 'x'. The following snapshot was obtained with this setting:

Version:
0.0.1 / 10/19/02
Author:
Elmar Grom
See Also:
Serialized Form

Nested Class Summary
private static class RuleInputField.FieldSpec
           
 
Nested classes/interfaces inherited from class javax.swing.JComponent
javax.swing.JComponent.AccessibleJComponent
 
Nested classes/interfaces inherited from class java.awt.Container
java.awt.Container.AccessibleAWTContainer
 
Nested classes/interfaces inherited from class java.awt.Component
java.awt.Component.AccessibleAWTComponent, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy
 
Field Summary
private  RuleTextField activeField
           
private  boolean backstep
           
private static int DEFAULT
          Used internally to identify the default setting for the return format.
static int DISPLAY_FORMAT
          Used to specify the retsult format.
static int ENCRYPTED
          Used to specify the retsult format.
private  Processor encryptionService
          Holds an instance of the Processor if one was specified and available
private  boolean hasParams
           
private  InstallData idata
           
private  java.util.Vector inputFields
          This Vector holds a reference to each input field, in the order in which they appear on the screen.
private  java.util.Vector items
           
static int PLAIN_STRING
          Used to specify the retsult format.
private  int resultFormat
           
private  java.lang.String separator
           
private static long serialVersionUID
           
static int SPECIAL_SEPARATOR
          Used to specify the retsult format.
private  java.awt.Toolkit toolkit
           
private  Validator validationService
          Holds an instance of the Validator if one was specified and available
private  java.util.Map validatorParams
           
 
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.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
RuleInputField(java.lang.String format, java.lang.String preset, java.lang.String separator, java.lang.String validator, java.util.Map validatorParams, java.lang.String processor, int resultFormat, java.awt.Toolkit toolkit, InstallData idata)
          Constructs a rule input field.
RuleInputField(java.lang.String format, java.lang.String preset, java.lang.String separator, java.lang.String validator, java.lang.String processor, int resultFormat, java.awt.Toolkit toolkit, InstallData idata)
          Constructs a rule input field.
 
Method Summary
 void caretUpdate(javax.swing.event.CaretEvent event)
          Called when the caret position is updated.
private  void createItems(java.lang.String format)
          Creates the items that make up this field.
 void focusGained(java.awt.event.FocusEvent event)
          Invoked when a component gains the keyboard focus.
 void focusLost(java.awt.event.FocusEvent event)
          Invoked when a component loses the keyboard focus.
 java.lang.String getFieldContents(int index)
          Returns the contents of the field indicated by index.
 int getNumFields()
          Returns the number of sub-fields composing this RuleInputField.
 java.lang.String getText()
          Returns the field contents, assembled acording to the encryption and separator rules.
 java.util.Map getValidatorParams()
          Returns the validator parameters, if any.
 boolean hasParams()
           
 void keyPressed(java.awt.event.KeyEvent event)
          This method is invoked when a key has been pressed.
 void keyReleased(java.awt.event.KeyEvent event)
          This method is invoked when a key has been released.
 void keyTyped(java.awt.event.KeyEvent event)
          This method is invoked when a key has been typed.
private  void setFields(java.lang.String data)
          Sets each field to a pre-defined value.
 boolean validateContents()
          This method validates the field content.
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getUIClassID, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update, updateUI
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, 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

serialVersionUID

private static final long serialVersionUID
See Also:
Constant Field Values

PLAIN_STRING

public static final int PLAIN_STRING
Used to specify the retsult format. This constant specifies to return the contents of all fields concatenated into one long string, with separation between each component.

See Also:
Constant Field Values

DISPLAY_FORMAT

public static final int DISPLAY_FORMAT
Used to specify the retsult format. This constant specifies to return the contents of all fields together with all separators as specified in the field format concatenated into one long string. In this case the resulting string looks just like the user saw it during data entry

See Also:
Constant Field Values

SPECIAL_SEPARATOR

public static final int SPECIAL_SEPARATOR
Used to specify the retsult format. This constant specifies to return the contents of all fields concatenated into one long string, with a special separator string inserted in between the individual components.

See Also:
Constant Field Values

ENCRYPTED

public static final int ENCRYPTED
Used to specify the retsult format. This constant specifies to return the contents of all fields in a somehow modified way. How the content is modified depends on the operation performed by a encryption service class. The class must be provided at object instatiation.

See Also:
Constant Field Values

DEFAULT

private static int DEFAULT
Used internally to identify the default setting for the return format.


items

private java.util.Vector items

inputFields

private java.util.Vector inputFields
This Vector holds a reference to each input field, in the order in which they appear on the screen.


hasParams

private boolean hasParams

validatorParams

private java.util.Map validatorParams

activeField

private RuleTextField activeField

backstep

private boolean backstep

toolkit

private java.awt.Toolkit toolkit

separator

private java.lang.String separator

resultFormat

private int resultFormat

idata

private InstallData idata

validationService

private Validator validationService
Holds an instance of the Validator if one was specified and available


encryptionService

private Processor encryptionService
Holds an instance of the Processor if one was specified and available

Constructor Detail

RuleInputField

public RuleInputField(java.lang.String format,
                      java.lang.String preset,
                      java.lang.String separator,
                      java.lang.String validator,
                      java.util.Map validatorParams,
                      java.lang.String processor,
                      int resultFormat,
                      java.awt.Toolkit toolkit,
                      InstallData idata)
Constructs a rule input field.

Parameters:
format - a string that specifies the formatting and to a limited degree the behavior of this field.
preset - a string that specifies preset values for specific sub-fields.
separator - a string to be used for separating the contents of individual fields in the string returned by getText()
validator - A string that specifies a class to perform validation services. The string must completely identify the class, so that it can be instantiated. The class must implement the RuleValidator interface. If an attempt to instantiate this class fails, no validation will be performed.
validatorParams - A java.util.Map containing name/ value pairs, which will be forwarded to the validator.
processor - A string that specifies a class to perform processing services. The string must completely identify the class, so that it can be instantiated. The class must implement the Processor interface. If an attempt to instantiate this class fails, no processing will be performed. Instead, the text is returned in the default formatting.
resultFormat - specifies in which format the resulting text should be returned, wehn getText() is called. The following values are legal:
  • PLAIN_STRING
  • DISPLAY_FORMAT
  • SPECIAL_SEPARATOR
  • ENCRYPTED
toolkit - needed to gain access to beep()

RuleInputField

public RuleInputField(java.lang.String format,
                      java.lang.String preset,
                      java.lang.String separator,
                      java.lang.String validator,
                      java.lang.String processor,
                      int resultFormat,
                      java.awt.Toolkit toolkit,
                      InstallData idata)
Constructs a rule input field.

Parameters:
format - a string that specifies the formatting and to a limited degree the behavior of this field.
preset - a string that specifies preset values for specific sub-fields.
separator - a string to be used for separating the contents of individual fields in the string returned by getText()
validator - A string that specifies a class to perform validation services. The string must completely identify the class, so that it can be instantiated. The class must implement the RuleValidator interface. If an attempt to instantiate this class fails, no validation will be performed.
processor - A string that specifies a class to perform processing services. The string must completely identify the class, so that it can be instantiated. The class must implement the Processor interface. If an attempt to instantiate this class fails, no processing will be performed. Instead, the text is returned in the default formatting.
resultFormat - specifies in which format the resulting text should be returned, wehn getText() is called. The following values are legal:
  • PLAIN_STRING
  • DISPLAY_FORMAT
  • SPECIAL_SEPARATOR
  • ENCRYPTED
toolkit - needed to gain access to beep()
Method Detail

hasParams

public boolean hasParams()
Returns:
true if this instance has any parameters to pass to the Validator instance.

getNumFields

public int getNumFields()
Returns the number of sub-fields composing this RuleInputField.

Specified by:
getNumFields in interface ProcessingClient
Returns:
the number of sub-fields

getFieldContents

public java.lang.String getFieldContents(int index)
                                  throws java.lang.IndexOutOfBoundsException
Returns the contents of the field indicated by index.

Specified by:
getFieldContents in interface ProcessingClient
Parameters:
index - the index of the sub-field from which the contents is requested.
Returns:
the contents of the indicated sub-field.
Throws:
java.lang.IndexOutOfBoundsException - if the index is out of bounds.

getValidatorParams

public java.util.Map getValidatorParams()
Returns the validator parameters, if any. The caller should check for the existence of validator parameters via the hasParams() method prior to invoking this method.

Returns:
a java.util.Map containing the validator parameters.

getText

public java.lang.String getText()
Returns the field contents, assembled acording to the encryption and separator rules.

Returns:
the field contents

createItems

private void createItems(java.lang.String format)
Creates the items that make up this field. Both separators and input fields are considered items. The items created are stored in items. In addition, all fields are stored in inputFields.

Parameters:
format - a string that specifies the layout of the input fields and separators.

setFields

private void setFields(java.lang.String data)
Sets each field to a pre-defined value.

Parameters:
data - a String containing the preset values for each field. The format of the string is as follows: The content for the individuals fields must be separated by whitespace. Each data block is preceeded by the index of the field to set (counting starts at 0) followed by a colon ':'and after that the actual data for the field.

validateContents

public boolean validateContents()
This method validates the field content. Validating is performed through a user supplied service class that provides the validation rules.

Returns:
true if the validation passes or no implementation of a validation rule exists. Otherwise false is returned.

keyTyped

public void keyTyped(java.awt.event.KeyEvent event)
This method is invoked when a key has been typed. The event occurs when a key press is followed by a key release.

Specified by:
keyTyped in interface java.awt.event.KeyListener
Parameters:
event - the key event forwarded by the system.

keyPressed

public void keyPressed(java.awt.event.KeyEvent event)
This method is invoked when a key has been pressed. This method verifies the condition of the input field in focus. Once the column count in the field has reached the specified maximum, the rule specified for the field in question is invoked. In case the test result is positive, focus is set to the next field. If hte test result is negative, the field content is marked and the caret set to the start of the field.

Specified by:
keyPressed in interface java.awt.event.KeyListener
Parameters:
event - the key event forwarded by the system.

keyReleased

public void keyReleased(java.awt.event.KeyEvent event)
This method is invoked when a key has been released.

Specified by:
keyReleased in interface java.awt.event.KeyListener
Parameters:
event - the key event forwarded by the system.

focusGained

public void focusGained(java.awt.event.FocusEvent event)
Invoked when a component gains the keyboard focus.

Specified by:
focusGained in interface java.awt.event.FocusListener
Parameters:
event - the focus event forwardes by the sytem.

focusLost

public void focusLost(java.awt.event.FocusEvent event)
Invoked when a component loses the keyboard focus. This method does nothing, we are only interested in 'focus gained' events.

Specified by:
focusLost in interface java.awt.event.FocusListener
Parameters:
event - the focus event forwardes by the sytem.

caretUpdate

public void caretUpdate(javax.swing.event.CaretEvent event)
Called when the caret position is updated.

Specified by:
caretUpdate in interface javax.swing.event.CaretListener
Parameters:
event - the caret event received from the text field