Reply

Building a Swing Validation Package with InputVerifier

At 5:46 AM on Aug 4, 2005, Michael Urban wrote:

Although there are multiple frameworks out there for validating user input in Swing, there is also an API in Swing called InputVerifier which is very easy to use, and extremely easy to customize. In this article, I build a reusable verification package based on InputVerifier, as well as provide some very useful verifiers that can be used out of the box in your own Swing applications.

The base class we will build on is InputVerifier in the javax.swing package. It has one abstract method we need to implement called verify() which takes a single JComponent as a parameter, and returns true or false depending on whether the component passed or failed validation respectively. Once we have implemented verify(), we can use it on a JTextField for example, as follows:

JTextField text = new JTextField();
text.setInputVerifier(new MyVerifier());

However, InputVerifier by itself is not very interesting. All it does is prevent the user from tabbing or mousing out of the component in question. That's pretty boring and also not very helpful to the user at helping them figure out why what they entered is invalid. But it does give us a base to build on for all of the cool things we will do in the much more capable validation package we build. I will start with a list of what I think a validation package should be able to do, and we will build our implementation based on that:

1. We should be able to change the background color of a component if the data is invalid.
2. We should be able to popup a tooltip like message next to the component indicating to the user what is wrong with the data, and what they need to fix.
3. We should notify the form of the state of its data after each component is validated, so it can perform any form specific actions it needs too (such as enabling or disabling Ok / Apply buttons based on validation state).
4. We should flag invalid data as soon as the user tries to leave the field with the invalid data, rather than wait until Apply or Ok is clicked.

Our package will consist of one abstract class which handles most of the work and only requires us to implement one method, that will determine the criteria that should be used to determine whether the entry is valid or not. We will also provide an interface that the dialogs we want to validate will implement. The interface will provide a standard way for our validators to notify forms of their current validation state so that they can perform any form specific actions they want to, such as enabling or disabling Ok / Apply buttons. With this in mind, lets start with the interface.

The WantsValidationStatus Interface

The following interface provides a way for our validators to trigger any dialog specific events you might want performed when the form is in an invalid state--for example, disabling Ok and/or Apply buttons. It also provides a way to trigger any dialog specific events you want performed when the form returns to a valid state, such as re-enabling those buttons:

package org.javalobby.validation;
 
public interface WantsValidationStatus {
    void validateFailed();  // Called when a component has failed validation.
    void validatePassed();  // Called when a component has passed validation.
}

Implementing this interface is optional, but if you don't do it, your dialog will not recieive any notication of current validation status. Note that it is not strictly necessary to disable Ok and Apply buttons, since InputVerifier won't let them actually do anything if there is invlalid data. But I think disabling them is a nice asthetic touch. With the interface out of the way, lets move on to the abstract class.

The AbstractValidator class

AbstactValidator is where most of the work regarding poping up help tips, changing the background color of the component, and notifying forms of their current validation state is done. It leaves only one abstract method undefined, protected abstract boolean validateCriteria(JComponent c) , which we need to provide in our implementations to control what logical criteria is actually used to validate the components. Here is the entire abstract class:

package org.javalobby.validation;
 
import java.awt.*;
import java.awt.event.*;
import javax.swing.*;
 
/**
 * This class handles most of the details of validating a component, including
 * all display elements such as popup help boxes and color changes.
 * 
 * @author Michael Urban
 * @version Beta 1
 * @see WantsValidationStatus
 */
 
public abstract class AbstractValidator extends InputVerifier implements KeyListener {
    private JDialog popup;
    private Object parent;
    private JLabel messageLabel;
    private JLabel image;
    private Point point;
    private Dimension cDim;
    private Color color;
	
    private AbstractValidator() {
        color = new Color(243, 255, 159);
    }
	
    private AbstractValidator(JComponent c, String message) {
        this();
        c.addKeyListener(this);
        messageLabel = new JLabel(message + " ");
        image = new JLabel(new ImageIcon("exception_16x16.png"));
    }
	
    /**
     * @param parent A JDialog that implements the ValidationCapable interface.
     * @param c The JComponent to be validated.
     * @param message A message to be displayed in the popup help tip if validation fails.
     */
	
    public AbstractValidator (JDialog parent, JComponent c, String message) {		
        this(c, message);
        this.parent = parent;
        popup = new JDialog(parent);
        initComponents();
    }
	
    /**
     * @param parent A JFrame that implements the ValidationCapable interface.
     * @param c The JComponent to be validated.
     * @param message A message to be displayed in the popup help tip if validation fails.
     */
	
    public AbstractValidator (JFrame parent, JComponent c, String message) {
        this(c, message);
        this.parent = parent;
        popup = new JDialog(parent);
        initComponents();
    }
	
    /**
     * Implement the actual validation logic in this method. The method should
     * return false if data is invalid and true if it is valid. It is also possible
     * to set the popup message text with setMessage() before returning, and thus
     * customize the message text for different types of validation problems.
     * 
     * @param c The JComponent to be validated.
     * @return false if data is invalid. true if it is valid.
     */
	
    protected abstract boolean validationCriteria(JComponent c);
	
    /**
     * This method is called by Java when a component needs to be validated.
     * It should not be called directly. Do not override this method unless
     * you really want to change validation behavior. Implement
     * validationCriteria() instead.
     */
	
    public boolean verify(JComponent c) {		
        if (!validationCriteria(c)) {
			
            if(parent instanceof WantsValidationStatus)
                ((WantsValidationStatus)parent).validateFailed();
			
            c.setBackground(Color.PINK);
            popup.setSize(0, 0);
            popup.setLocationRelativeTo(c);
            point = popup.getLocation();
            cDim = c.getSize();
            popup.setLocation(point.x-(int)cDim.getWidth()/2,
                point.y+(int)cDim.getHeight()/2);
            popup.pack();
            popup.setVisible(true);
            return false;
        }
        
        c.setBackground(Color.WHITE);
		
        if(parent instanceof WantsValidationStatus)
            ((WantsValidationStatus)parent).validatePassed();
		
        return true;
    }
	
    /**
     * Changes the message that appears in the popup help tip when a component's
     * data is invalid. Subclasses can use this to provide context sensitive help
     * depending on what the user did wrong.
     * 
     * @param message
     */
	
    protected void setMessage(String message) {
       messageLabel.setText(message);
    }
	
     /**
      * @see KeyListener
      */
	
    public void keyPressed(KeyEvent e) {
        popup.setVisible(false);
    }
	
    /**
     * @see KeyListener
     */
	
    public void keyTyped(KeyEvent e) {}
	
    /**
     * @see KeyListener
     */
	
    public void keyReleased(KeyEvent e) {}
	
    private void initComponents() {
        popup.getContentPane().setLayout(new FlowLayout());
        popup.setUndecorated(true);
        popup.getContentPane().setBackground(color);
        popup.getContentPane().add(image);
        popup.getContentPane().add(messageLabel);
        popup.setFocusableWindowState(false);
    }
}

Most of the work in this class happens in the verify() method, but lets start by taking a look at the constructor. We provide four overloaded versions, but only the last two are designed to be called outside the class. Parent is, of course, the parent dialog of the component that wants to be validated. The Color instance that we create will be used for the background color of our popup help tip--the hard coded color in this example giving us a pale yellow color. We register ourselves as a KeyListener for the component so that we can automatically hide our popup help tip when the user starts to type. Our AbstractValidator class implements the KeyListener interface, and we provide the methods required by the interface at the bottom of the class.

The instance of JDialog we create next is what will serve as our popup help tip. We change its layout to FlowLayout to make it easier to add our icon and message, and set it to be undecorated so it has no window decorations and no borders. The JDialog we create here will always stay ontop of its parent, even if we move focus away from it. messageLabel is our help message for the popup tip--the additional space appended on the end simply making it a bit more asthetically pleasing. image is, of course, a small icon which we also place in the popup tip. In this case, we have crudely hard-coded a file name which must be in a place where the class can find it. Something that would be worth adding here is a mutator method for the JLabel so that we can set the icon in our implementation classes, perhaps even using different icons for different kinds of problems. Next we just set the background color of the JDialog contentPane, and add our image and label to it. Finally, because we don't want our popup tip to steal focus from the component when it is displayed (or to get focus if the user clicks on it, we call setFocusableWindowState(false) on it.

The abstract method validationCriteria() is where the validation logic will go in our concrete implementations of AbstractValidator, so we will talk about that a bit later when we actually create some validators. For now, lets move on to the verify() method

The verify() Method

boolean verify(JComponent c) is called by Java when our component needs validation--in otherwords, when a user tries to remove focus from the component. Most of this is just standard Swing code that will be familar to most Java developers, so we won't go into much detail on it. It is easiest to set the location of our popup dialog before we size it, so we initially set its size to zero, and then set its location relative to the component which will place the upper left corner in the middle of the dialog. After that, we reset the location based on the size of the component in question and finally pack it.

Notce also that we check if our parent is an instance of WantsValidationStatus before actually calling the methods in that interface, making it optional for our dialogs to implement the interface. If they don't, they simply won't be notified of validation status changes.

In the followup post to this, I will provide a couple of examples of actual validators we built based on the AbstractValidator class. Feel free you use them in your own applications if you wish. The validator implementations are here:

Credit Card Validation with AbstractValidator

Here is a screenshot of what our final product looks like: