Class CharDocFilter

java.lang.Object
javax.swing.text.DocumentFilter
org.bzdev.swing.text.CharDocFilter

public class CharDocFilter extends DocumentFilter
Document Filter to implement character-based constraints. This class provides the ability to control which characters can be entered into a text field on a character-by-character basis, and whether the character will be the only character in the text field, a starting character, and ending character, or a character that can appear in any position. Specific starting or ending characters are optional. Generally additional constraints on text field will be needed. During editing, however, it is useful to limit the characters that can entered without over-constraining the user: sometimes during editing, the contents of the text field may be temporarily invalid.

The class is controlled by several methods:

  • The method optSingleChar determines if a character can be used as the full contents of a text field. In a text field representing a number, for example, one might want to enter '*' to indicate that any number is suitable. A character for which this method returns true must not be one for which optLeadingChar, allowedChar, or optTrailingChar return true.
  • The method mapSingleChar allows one single character entered to be replaced with another automatically. for example, if a text field contains the maximum number of lines to be displayed in a window, then one might want to use '*' or infinity to indicate that there is no limit, replacing a '*' with the Unicode character for 'infinity'.
  • The method optLeadingChar determines if a character is one that can appear only at the start of a text field.
  • The method allowedChar determines if a character is allowed in general (i.e., in any position, but not before an optional leading character and not after an optional trailing character.
  • The method optTrailingChar determines if a character can be the last character in the text field.
These methods may be subclassed to implement the desired behavior. Alternatively, one may call a series of methods (setOptSingleChars, setSingleCharMap setOptLeadingChars, setAllowedChar, or setOptTrailingChars to specify the behavior with control strings (when suitable, this will simply localization and internationalization.)

This is sufficient for handling cases such as numbers. An integer may, for example, start with a '-' but otherwise it will just contain digits. Accountants, however, prefer to surround a number with '(' and ')' to indicate negative numbers. This class can handle such uses.

See Also:
  • Constructor Details

    • CharDocFilter

      public CharDocFilter()
      Constructor.
  • Method Details

    • setOptSingleChars

      public void setOptSingleChars(String string)
      Set the characters for which optSingleChar will return true.
      Parameters:
      string - a string containing the legal characters; null if optSingleChar should always return false
    • setSingleCharMap

      public void setSingleCharMap(String string)
      Set the replacement map for optional single characters. Both the characters and the replacements should be such that optSingleChar(ch) returns true for each character ch in string; otherwise the pair will be ignored when mapSingleChar(ch) is called. This replacement applies only to optional single characters. For example, one might want to allow a user to enter a '*' to indicate an unbounded value and have a text box display the unicode character representing infinity.
      Parameters:
      string - a string containing pairs of characters, the first of a pair being a character to replace and the second in the pair being the replacement; null if no replacement is desired.
    • setOptLeadingChars

      public void setOptLeadingChars(String string)
      Set the characters for which optLeadingChar will return true.
      Parameters:
      string - a string containing the legal characters; null if optLeadingChar should always return false
    • setAllowedChars

      public void setAllowedChars(String string)
      Set the characters for which allowedChar will return true.
      Parameters:
      string - a string containing pairs of legal characters, each pair delimiting a range of characters for which if allowedChar should always return true; an empty string if allowedChar should always return false; a null string if allowedChar should always return true
    • setOptTrailingChars

      public void setOptTrailingChars(String string)
      Set the characters for which optTrailingChar will return true.
      Parameters:
      string - a string containing the legal characters; null if optSingleChar should always return false.
    • optSingleChar

      protected boolean optSingleChar(char ch)
      Check for optional single character. A matching character will be allowed as the only character in the text field, and may be entered only when the text field is empty.
      Parameters:
      ch - the last character to be placed into the text field
      Returns:
      true if an optional character; false otherwise
    • mapSingleChar

      protected char mapSingleChar(char ch)
      Get a replacement character for an optional single character. The replacement character ch must also be one for which optSingleChar(ch) will return true.
      Parameters:
      ch - the character entered into the text field.
      Returns:
      the replacement character if any; otherwise the original character passed in the argument
    • optLeadingChar

      protected boolean optLeadingChar(char ch)
      Check for optional leading character. An optional leading character must be inserted at the start of a text field, and a character cannot be inserted before an optional leading character.
      Parameters:
      ch - the last character typed
      Returns:
      true if an optional character; false otherwise
    • allowedChar

      protected boolean allowedChar(char ch)
      Check for a legal character.
      Parameters:
      ch - the last character typed.
      Returns:
      true if an allowed character; false otherwise
    • optTrailingChar

      protected boolean optTrailingChar(char ch)
      Check for an optional trailing character.
      Parameters:
      ch - the last character typed.
      Returns:
      true if an optional character; false otherwise
    • insertString

      public void insertString(DocumentFilter.FilterBypass fb, int offs, String str, AttributeSet a) throws BadLocationException
      Invoked prior to insertion of text into the specified Document. Subclasses that want to conditionally allow insertion should override this and only call supers implementation as necessary, or call directly into the FilterBypass.
      Overrides:
      insertString in class DocumentFilter
      Parameters:
      fb - FilterBypass that can be used to mutate Document
      offs - the offset into the document to insert the content >= 0. All positions that track change at or after the given location will move.
      str - the string to insert
      a - the attributes to associate with the inserted content. This may be null if there are no attributes.
      Throws:
      BadLocationException - the given insert position is not a valid position within the document
    • replace

      public void replace(DocumentFilter.FilterBypass fb, int offs, int length, String str, AttributeSet a) throws BadLocationException
      Invoked prior to replacing a region of text in the specified Document. Subclasses that want to conditionally allow replace should override this and only call supers implementation as necessary, or call directly into the FilterBypass.
      Overrides:
      replace in class DocumentFilter
      Parameters:
      fb - FilterBypass that can be used to mutate Document
      offs - Location in Document
      length - Length of text to delete
      str - Text to insert, null indicates no text to insert
      a - AttributeSet indicating attributes of inserted text, null is legal.
      Throws:
      BadLocationException - the given insert position is not a valid position within the document
    • remove

      public void remove(DocumentFilter.FilterBypass fb, int offs, int length) throws BadLocationException
      Invoked prior to removal of the specified region in the specified Document. Subclasses that want to conditionally allow removal should override this and only call supers implementation as necessary, or call directly into the FilterBypass as necessary.
      Overrides:
      remove in class DocumentFilter
      Parameters:
      fb - FilterBypass that can be used to mutate Document
      offs - the offset from the beginning >= 0
      length - the number of characters to remove >= 0
      Throws:
      BadLocationException - some portion of the removal range was not a valid part of the document. The location in the exception is the first bad position encountered.