Java Swing, 2nd Edition

The DocumentFilter Class

DocumentFilter is a class that oversees calls to insertString( ), remove( ), and replace( ) on any subclass of AbstractDocument. It can allow the edit to occur, substitute another edit, or block it entirely. Because all of Swing’s Document classes inherit from AbstractDocument, this means you can attach a DocumentFilter to pretty much any Swing text component. The Document interface does not define a setDocumentFilter( ) method though, so you have to cast the object returned by the getDocument( ) method to AbstractDocument before you can set the DocumentFilter. DocumentFilter was introduced in SDK 1.4.

Here’s how DocumentFilter works. AbstractDocument’s insertString( ), remove( ), and replace( ) methods check for the existence of a DocumentFilter. If there is one, they forward the call to the like-named method of the DocumentFilter object. But the DocumentFilter methods are passed an extra parameter called the FilterBypass. The FilterBypass object has its own insertString( ), remove( ), and replace( ) methods, and these actually change the Document’s content.

It’s important that DocumentFilter methods call FilterBypass methods because an endless calling loop occurs if the Document methods are called. The delegation to the DocumentFilter is “bypassed” in FilterBypass. FilterBypass also provides a getDocument( ) method so the DocumentFilter can examine the contents of the Document before deciding whether to allow an edit.

Constructor

public DocumentFilter( ) ...