Have you ever tried to make a textfield that accepts only 20 characters? Or a text area that automatically converts the user typed letters to upper case? Swing’s Document Listener is the most accurate and hassle-free way to achieve this in Swing. This articles explains you what you need to get started with Document Filter. Step by Step.

Let’s Make a MaxTextField

Let’s start by defining the problem. We are trying to add a TextField that will accept only 20 characters. After typing 20 characters the user cannot enter any more characters either by keypress or copy-paste. The user can however, delete existing characters and type new ones as long as the total number of characters is less than or equal to 20.

The Dirty way: Using KeyEvent.consume()

One’s first reaction would be to add a key listener to the textfield and calling the consume() method in a listener method like keyTyped() when the no. of characters exceeds 20.

Here’s the sample code that one would be templted to right

//Assume that textField is an instance of JTextField
textField.addKeyListener(new KeyAdapter(){
 public void keyTyped(KeyEvent e) {
  if(textField.getText().length() > 20){
  //Consume if the user has typed more than 20 charactes
  e.consume();
 }
}
}

This would seem to work fine. But there’s a catch. after typing 20 characters, the user can still insert more characters in the textfield by copy-pasting the text!!! why does this not work? Because, the paste happens at keyPress not keyTyped.
So, what’s the solution? We could add code in the keyPressed() that could handle ctrl+v. But what about shift+ins? What about right click and paste?
Started Sounding messy right? But the most itchy part of using this technique is this. When multiple keylisteners are attached to a textfield, there is no guarantee that which one will be called first. so, calling consume() on one listener does not prevent other listener from seeing this event! So when one listener is preventing the data from being entered, the other listener might happily be checking the spelling and underline the word in red(for a wrong spelling) even thought the user sees no character typed!!!

Enter DocumentFilter

What follows from the above discussion is this

“We need a technique that prevents more than 20 characters from being entered in the textfield before it reaches the textfield, not a technique that removes the character after it’s already there”

The solution is to use a document filter. What’s a document filter? Before that, What’s a document in the first place? A document is something like a container that sort-of stores the text entered in any text component in Swing. Each text component in swing has it’s own Document. It’s kind of a model for the swing-text-based-ui components. Got it?
Ok, so now what’s a DocumentFilter? Simple. A document filter is a special class that can be attached to documents to filter out the data before it goes into the document.

How to implement a DocumentFilter:

You simply follow the following steps

• Write a class extending the DocumentFilter class
• override one or many of insertString(), remove() or replace() methods, depending on whether you are filtering string insertion, string removal or string-replacement operations.
• you grab the document of the textfield and attach an instance of this document filter to that document

Let’s start. Here’s the DocumentFilter class for our problem. Clearly we need to override the insertString() and replace() methods so that user may not enter more than 20 characters why inserting or replacing strings. Here’s the code. See comments for more details

Step 1) Writing the class:

class MyDocumentFilter extends DocumentFilter{
 public void replace(FilterBypass fb, int offset, int length,
      String text, AttributeSet attrs) throws BadLocationException {
 
 //The current length minus the no.of characters deleted plus the
 // number of characters inserted is the final length in the textfield
 //and should not be more than 20
 if ((fb.getDocument().getLength() + text.length() - length) <= 20){
	super.replace(fb, offset,length, text, attrs);
 }
 else{
 	//Let's beep if the user tries to enter more characters
 	Toolkit.getDefaultToolkit().beep();
 }
}
public void insertString(FilterBypass fb, int offset,
       String string, AttributeSet attr) throws BadLocationException {
 
  //While inserting the current length plus the number of characters inserted
  //is the final length in the textfield and should not be more than 20
  if ((fb.getDocument().getLength() + string.length()) <= 20){
    super.insertString(fb, offset,string, attr);
  }
  else{
    //Let's beep if the user tries to enter more characters
   Toolkit.getDefaultToolkit().beep();
  }
 }
}

Step 2) Attach an instance of this class to the textfields document.

This is a simple and one line code as below

((AbstractDocument)textField.getDocument())
.setDocumentFilter(new MyDocumentFilter());

A small point to note is that we need to cast the return type of getDocument() to AbstractDocument, only which has the setDocumentFilter method.

That’s it! Hope you found this article interesting.