java.lang.Object
javax.swing.text.DocumentFilter
org.bzdev.swing.text.CharDocFilter
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 whichoptLeadingChar
,allowedChar
, oroptTrailingChar
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.
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:
-
Nested Class Summary
Nested classes/interfaces inherited from class javax.swing.text.DocumentFilter
DocumentFilter.FilterBypass
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionprotected boolean
allowedChar
(char ch) Check for a legal character.void
insertString
(DocumentFilter.FilterBypass fb, int offs, String str, AttributeSet a) Invoked prior to insertion of text into the specified Document.protected char
mapSingleChar
(char ch) Get a replacement character for an optional single character.protected boolean
optLeadingChar
(char ch) Check for optional leading character.protected boolean
optSingleChar
(char ch) Check for optional single character.protected boolean
optTrailingChar
(char ch) Check for an optional trailing character.void
remove
(DocumentFilter.FilterBypass fb, int offs, int length) Invoked prior to removal of the specified region in the specified Document.void
replace
(DocumentFilter.FilterBypass fb, int offs, int length, String str, AttributeSet a) Invoked prior to replacing a region of text in the specified Document.void
setAllowedChars
(String string) Set the characters for which allowedChar will return true.void
setOptLeadingChars
(String string) Set the characters for which optLeadingChar will return true.void
setOptSingleChars
(String string) Set the characters for whichoptSingleChar
will return true.void
setOptTrailingChars
(String string) Set the characters for which optTrailingChar will return true.void
setSingleCharMap
(String string) Set the replacement map for optional single characters.
-
Constructor Details
-
CharDocFilter
public CharDocFilter()Constructor.
-
-
Method Details
-
setOptSingleChars
Set the characters for whichoptSingleChar
will return true.- Parameters:
string
- a string containing the legal characters; null if optSingleChar should always return false
-
setSingleCharMap
Set the replacement map for optional single characters. Both the characters and the replacements should be such thatoptSingleChar(ch)
returns true for each characterch
instring
; otherwise the pair will be ignored whenmapSingleChar(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
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
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
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 characterch
must also be one for whichoptSingleChar(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 classDocumentFilter
- Parameters:
fb
- FilterBypass that can be used to mutate Documentoffs
- 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 inserta
- 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 classDocumentFilter
- Parameters:
fb
- FilterBypass that can be used to mutate Documentoffs
- Location in Documentlength
- Length of text to deletestr
- Text to insert, null indicates no text to inserta
- 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 classDocumentFilter
- Parameters:
fb
- FilterBypass that can be used to mutate Documentoffs
- the offset from the beginning >= 0length
- 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.
-