Package ca.cgjennings.ui

Class FilteredDocument

  • All Implemented Interfaces:
    java.io.Serializable, javax.swing.text.Document
    public class FilteredDocument
extends javax.swing.text.PlainDocument
    An extension of PlainDocument that transparently filters out certain characters. A set of characters is provided as a string, and the filter operates as either a white list (allowing only characters in the filter string) or a black list (allowing all characters except those in the filter string).
    Author:
    Chris Jennings
    See Also:
    Serialized Form

    • Nested Class Summary

      • Nested classes/interfaces inherited from class javax.swing.text.AbstractDocument

        javax.swing.text.AbstractDocument.AbstractElement, javax.swing.text.AbstractDocument.AttributeContext, javax.swing.text.AbstractDocument.BranchElement, javax.swing.text.AbstractDocument.Content, javax.swing.text.AbstractDocument.DefaultDocumentEvent, javax.swing.text.AbstractDocument.ElementEdit, javax.swing.text.AbstractDocument.LeafElement

    • Field Summary

      • Fields inherited from class javax.swing.text.PlainDocument

        lineLimitAttribute, tabSizeAttribute

      • Fields inherited from class javax.swing.text.AbstractDocument

        BAD_LOCATION, BidiElementName, ContentElementName, ElementNameAttribute, listenerList, ParagraphElementName, SectionElementName

      • Fields inherited from interface javax.swing.text.Document

        StreamDescriptionProperty, TitleProperty

    • Constructor Summary

      Constructors 
      Constructor Description
      FilteredDocument()
      Creates a filtered document that allows all characters.
      FilteredDocument​(java.lang.String blackList)
      Creates a filtered document that filters out the characters in the filter list.
      FilteredDocument​(java.lang.String filterList, boolean isWhiteList)
      Creates a filtered document with the specified filter characters and list type.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static javax.swing.text.PlainDocument createDigitDocument()
      Returns a new document that filters out non-digits.
      static javax.swing.text.PlainDocument createFileNameDocument()
      Returns a new document that filters out characters that are illegal in Windows, *NIX file names.
      static javax.swing.text.PlainDocument createFilePathDocument()
      Returns a new document that filters out characters that are illegal in Windows, *NIX file paths.
      static javax.swing.text.PlainDocument createHexDocument()
      Returns a new document that accepts hex digits.
      static javax.swing.text.PlainDocument createJavaNameDocument()
      Returns a document that only accepts characters that can appear in a Java class name.
      static javax.swing.text.PlainDocument createLowerCaseDocument​(java.util.Locale locale)
      Returns a new document that converts all text to lower case.
      static javax.swing.text.PlainDocument createPropertyKeyDocument()
      Returns a new document that filters out characters that are escaped in property files.
      static javax.swing.text.PlainDocument createUpperCaseDocument​(java.util.Locale locale)
      Returns a new document that converts all text to upper case.
      java.lang.String filterString​(java.lang.String text)
      Returns the result of filtering a string with the document's filter.
      java.lang.String getFilteredCharacters()
      Returns the characters being filtered as a string.
      void insertString​(int offs, java.lang.String str, javax.swing.text.AttributeSet a)
      Performs filtering of characters when new text is inserted into the document being calling the super implementation to actually insert the (filtered) text.
      boolean isWhiteList()
      Returns true if the filter characters form a white list (list of the allowed characters), or false if they form a black list (list of excluded characters).
      protected void onFiltration​(java.lang.String oldString, java.lang.String newString)
      Override to react to a string having characters filtered out.
      void setFilteredCharacters​(java.lang.String filterList)
      Sets the list of characters to include/exclude.
      void setWhiteList​(boolean isWhiteList)
      Sets whether the list is treated as a white list (true) or black list (false).

      • Methods inherited from class javax.swing.text.PlainDocument

        createDefaultRoot, getDefaultRootElement, getParagraphElement, insertUpdate, removeUpdate

      • Methods inherited from class javax.swing.text.AbstractDocument

        addDocumentListener, addUndoableEditListener, createBranchElement, createLeafElement, createPosition, dump, fireChangedUpdate, fireInsertUpdate, fireRemoveUpdate, fireUndoableEditUpdate, getAsynchronousLoadPriority, getAttributeContext, getBidiRootElement, getContent, getCurrentWriter, getDocumentFilter, getDocumentListeners, getDocumentProperties, getEndPosition, getLength, getListeners, getProperty, getRootElements, getStartPosition, getText, getText, getUndoableEditListeners, postRemoveUpdate, putProperty, readLock, readUnlock, remove, removeDocumentListener, removeUndoableEditListener, render, replace, setAsynchronousLoadPriority, setDocumentFilter, setDocumentProperties, writeLock, writeUnlock

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • FilteredDocument

        public FilteredDocument()
        Creates a filtered document that allows all characters.

      • FilteredDocument

        public FilteredDocument​(java.lang.String blackList)
        Creates a filtered document that filters out the characters in the filter list.
        Parameters:
        blackList - the characters to exclude
        Throws:
        java.lang.NullPointerException - if filterList is null

      • FilteredDocument

        public FilteredDocument​(java.lang.String filterList,
                        boolean isWhiteList)
        Creates a filtered document with the specified filter characters and list type.
        Parameters:
        filterList - the characters to include/exclude
        isWhiteList - whether the filter includes or excludes the filter list
        Throws:
        java.lang.NullPointerException - if filterList is null

    • Method Detail

      • setWhiteList

        public void setWhiteList​(boolean isWhiteList)
        Sets whether the list is treated as a white list (true) or black list (false).
        Parameters:
        isWhiteList - true if the filter characters are allowed

      • isWhiteList

        public boolean isWhiteList()
        Returns true if the filter characters form a white list (list of the allowed characters), or false if they form a black list (list of excluded characters).
        Returns:
        true if the list is a white list

      • setFilteredCharacters

        public void setFilteredCharacters​(java.lang.String filterList)
        Sets the list of characters to include/exclude.
        Parameters:
        filterList - each character in this string will be excluded or included (depending on whether the set is a whitelist)
        Throws:
        java.lang.NullPointerException - if filterList is null

      • getFilteredCharacters

        public java.lang.String getFilteredCharacters()
        Returns the characters being filtered as a string.
        Returns:
        the characters to include/exclude

      • insertString

        public void insertString​(int offs,
                         java.lang.String str,
                         javax.swing.text.AttributeSet a)
                  throws javax.swing.text.BadLocationException
        Performs filtering of characters when new text is inserted into the document being calling the super implementation to actually insert the (filtered) text.
        Specified by:
        insertString in interface javax.swing.text.Document
        Overrides:
        insertString in class javax.swing.text.PlainDocument
        Parameters:
        offs - offset into the document
        str - the string to insert
        a - attributes for the inserted text (typically null)
        Throws:
        javax.swing.text.BadLocationException - if the offset is not within the document bounds (0..document.length())

      • onFiltration

        protected void onFiltration​(java.lang.String oldString,
                            java.lang.String newString)
        Override to react to a string having characters filtered out. The default implementation emits an error beep.
        Parameters:
        oldString - the original string that was to be inserted into the document
        newString - the (possibly empty) filtered string

      • createFileNameDocument

        public static final javax.swing.text.PlainDocument createFileNameDocument()
        Returns a new document that filters out characters that are illegal in Windows, *NIX file names.
        Returns:
        a file name filtering document

      • createFilePathDocument

        public static final javax.swing.text.PlainDocument createFilePathDocument()
        Returns a new document that filters out characters that are illegal in Windows, *NIX file paths. This is identical to the filter created with createFileNameDocument(), but it does not filter path characters.
        Returns:
        a file path filtering document

      • createDigitDocument

        public static final javax.swing.text.PlainDocument createDigitDocument()
        Returns a new document that filters out non-digits.
        Returns:
        a document that accepts only digits

      • createPropertyKeyDocument

        public static final javax.swing.text.PlainDocument createPropertyKeyDocument()
        Returns a new document that filters out characters that are escaped in property files.
        Returns:
        a property key filtering document

      • createLowerCaseDocument

        public static final javax.swing.text.PlainDocument createLowerCaseDocument​(java.util.Locale locale)
        Returns a new document that converts all text to lower case.
        Parameters:
        locale - the locale to use for conversion
        Returns:
        a document that allows only lower case, converting if necessary

      • createUpperCaseDocument

        public static final javax.swing.text.PlainDocument createUpperCaseDocument​(java.util.Locale locale)
        Returns a new document that converts all text to upper case.
        Parameters:
        locale - the locale to use for conversion
        Returns:
        a document that allows only upper case, converting if necessary

      • createHexDocument

        public static final javax.swing.text.PlainDocument createHexDocument()
        Returns a new document that accepts hex digits. Alphabetic digits are converted to upper case.
        Returns:
        a document that accepts only hex digits 0-9, a-f, and A-F

      • createJavaNameDocument

        public static final javax.swing.text.PlainDocument createJavaNameDocument()
        Returns a document that only accepts characters that can appear in a Java class name. Note that the document will not prevent the initial character from being a digit.
        Returns:
        a document that accepts only Java identifier characters

      • filterString

        public java.lang.String filterString​(java.lang.String text)
        Returns the result of filtering a string with the document's filter. As a side effect, the document content will be replaced by the filtered text.
        Parameters:
        text - the text to filter
        Returns:
        the text that remains after applying the filter