org.shetline.gui
Class KTextField

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.text.JTextComponent
                  javax.swing.JTextField
                      org.shetline.gui.KTextField

All Implemented Interfaces:

ImageObserver, MenuContainer, Serializable, Accessible, Scrollable, SwingConstants

Direct Known Subclasses:

SearchField

public class KTextField
extends JTextField

KTextField is a subclass of JTextField with extra features which include:

• The option to add simple TextListeners.
• Valid character filtering and length checking, including enforcement of a maximum byte length under a specified byte encoding and automatic uppercase or lowercase input conversion.
• The option to show suggested text that appears (by default in light gray) in a text field while the field is empty and out of focus.
• The option to show a pop-up list of suggested text that a user can select by mouse click or keyboard navigation.
• The option to display a visual error state for text fields containing invalid input.
• The ability to track user-typed changes distinctly from programmatic changes, visually indicate that a text field has been edited, and to either accept user-typed changes or restore an initial base text state.
• The option to add an alternate type of text change listener which receives ActionEvents after a programmable delay following typed input, a delay which is restarted with each keystroke until keystrokes stop for the duration of the specified delay. Event notification can optionally occur outside of the AWT event dispatch thread.
• Customizable background color to distinguish editable from non-editable text fields.

See Also:

Serialized Form

Nested Class Summary

static class	KTextField.CaseMode
static class	KTextField.ErrorState
protected class	KTextField.StatusBorder

Nested classes/interfaces inherited from class javax.swing.JTextField

JTextField.AccessibleJTextField

Nested classes/interfaces inherited from class javax.swing.text.JTextComponent

JTextComponent.AccessibleJTextComponent, JTextComponent.DropLocation, JTextComponent.KeyBinding

Nested classes/interfaces inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

protected boolean	altIsDown
protected String	baseText
protected String	byteEncoding
protected KTextField.CaseMode	caseMode
protected boolean	checkLengthInBytes
protected CharsetEncoder	currentEncoder
static Color	DEFAULT_EDITABLE_BACKGROUND
static Color	DEFAULT_ERROR_BACKGROUND
static Icon	DEFAULT_ERROR_ICON
static Color	DEFAULT_MODIFIED_TEXT_COLOR
static Color	DEFAULT_SUGGESTION_TEXT_COLOR
static int	DEFAULT_TYPING_UPDATE_DELAY
protected Color	defaultBackground
protected Border	defaultBorder
protected Color	defaultForeground
protected DocumentListener	docListener
protected Color	editableBackground
protected Color	errorBackground
protected Icon	errorIcon
protected KTextField.ErrorState	errorState
protected Border	explicitBorder
protected Color	explicitDisabledBackground
protected Color	explicitStandardTextColor
protected boolean	focusRegainedFromPopup
protected boolean	hasBeenEdited
protected static int	ICON_GAP
protected int	ignoreDocumentChange
protected String	lastText
protected boolean	leftToRight
protected int	maxLength
protected Color	modifiedTextColor
protected PopupNavigator	navigator
protected Container	parent
protected JPopupMenu	popup
protected PopupMenuListener	popupMenuListener
protected String[]	popupSuggestions
protected PropertyChangeListener	propertyChangeListener
protected Set<AWTKeyStroke>	savedForwardTraversalKeys
protected int	savedSelectionEnd
protected int	savedSelectionStart
protected boolean	showModified
protected boolean	suggestionShowing
protected String	suggestionText
protected Color	suggestionTextColor
protected String	suppressNextPopupFor
protected int	textCheckLength
protected boolean	textCheckPending
protected int	textCheckStart
protected ListenerHandler	textListenerHandler
protected DelayedAction	typingDelay
protected ListenerHandler	typingListenerHandler
protected Pattern	validCharacterPattern

Fields inherited from class javax.swing.JTextField

notifyAction

Fields inherited from class javax.swing.text.JTextComponent

DEFAULT_KEYMAP, FOCUS_ACCELERATOR_KEY

Fields inherited from class javax.swing.JComponent

accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface javax.swing.SwingConstants

BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

KTextField()
Constructs a new empty KTextField.

KTextField(Document doc, String text, int columns)
Constructs a new KTextField which uses the specified text storage model, text content, and number of columns.

KTextField(int columns)
Constructs a new empty KTextField with the specified number of columns.

KTextField(String text)
Constructs a new KTextField initialized with the specified text.

KTextField(String text, int columns)
Constructs a new KTextField initialized with the specified text and column width.

Method Summary

void	accept() Make the current content of the text field the base text for the field, and mark the text field as unedited.
void	addNotify()
void	addTextListener(TextListener listener) Adds the specified text event listener to receive text events from this text field.
void	addTypingListener(ActionListener listener) Add an ActionListener which will be called in response to typing changes, once changes have stopped occurring for a specified typing update delay (which defaults to 250 msec.
void	addTypingListener(ActionListener listener, boolean awtNotify) Add an ActionListener which will be called in response to typing changes, once changes have stopped occurring for a specified typing update delay (which defaults to 250 msec.
protected void	beep()
protected void	broadcastTextChange()
protected void	checkTextChange(int start, int length)
protected void	checkTextChangeAux(int start, int length)
void	clearError() Clears the error state of the text field.
protected Border	createOuterBorder()
String	getByteEncoding() Returns the byte encoding (such as "UTF-8") used to measure the length of the text field in bytes.
KTextField.CaseMode	getCaseMode() Returns the current case conversion mode of the text field, one of CaseMode.NO_CHANGE, CaseMode.TO_UPPER, or CaseMode.TO_LOWER.
Color	getDisabledBackground() Returns the background color used to show that the text field is disabled.
Color	getEditableBackground() Returns the background color used to show that the text field is editable.
Color	getErrorBackground() Returns the background color used to show that the text field is in an error state.
Icon	getErrorIcon() Returns the Icon currently being used to show error conditions.
KTextField.ErrorState	getErrorState() Returns one of the following enumerated values: ErrorState.NO_ERROR, ErrorState.TRANSIENT_ERROR, or ErrorState.PERSISTENT_ERROR, representing the error state of the text field.
boolean	getHasBeenEdited() Returns true if the text field has been edited, that is, if the text field's current content differs from its current base text.
int	getLength() Returns the length in characters of the current content of the text field.
int	getMaximumLength() Returns the maximum length allowed for text input.
int	getMeasuredLength() Returns the current length of the text field, measured in characters or bytes, depending on which length is currently being enforced for maximum length.
protected int	getMeasuredLength(String s)
Color	getModifiedTextColor() Returns the color used to show that the text field has been edited by user input.
boolean	getShowModified() Returns true if the text field shows edited text in a different color from unmodified text.
Color	getStandardTextColor() Returns the color used to show standard text.
protected Insets	getStatusBorderInsets()
String	getSuggestionText() Returns the text which will be shown as suggested or example input when the text field is empty and doesn't have focus, or null if there is no suggested text.
Color	getSuggestionTextColor() Returns the color used to show suggested text.
protected String	getText_JTextField() For subclasses of KTextField, access to JTextComponent.getText().
String	getText() Returns the content of this text field, an empty string if the text field's Document is null or if the content is undefined.
int	getTypingUpdateDelay() Returns the delay, in milliseconds, used between the last typed-in text change and notifications of ActionListeners registered with addTypingListener(java.awt.event.ActionListener, boolean).
Border	getUserBorder() Returns the border set by the user (or by the current look and feel) for this component, rather than the compound border created by combining the user border with this component's inner status border.
boolean	hasError() Returns true if the text field is flagged as being in error.
static boolean	isCharacterInputEvent(KeyEvent event) Determine if event represents simple character input, as opposed to action keys, backspaces, cursor movement, etc.
boolean	isCheckingEncodedLength() Returns true if text field maximum length is being checked using encoded byte length rather than character length.
boolean	isEmpty() Check if the text field is empty, disregarding any suggestion text that may currently be shown.
protected boolean	isReallyEmpty() Check if the text field is empty of both regular text and suggestion text.
protected boolean	isValidCharacter(char ch)
protected void	KTextFieldX()
protected void	paintStatusBorder(Graphics g, int x, int y, int width, int height)
protected void	processKeyEvent_JTextField(KeyEvent event) For subclasses of KTextField, access to JComponent.processKeyEvent(KeyEvent).
protected void	processKeyEvent(KeyEvent event)
protected void	refreshBorder()
void	removeNotify()
void	removeTextListener(TextListener listener) Removes the specified text event listener so that it no longer receives text events from this text field.
void	removeTypingListener(ActionListener listener) Removes the specified ActionListener so that it no longer receives typing change events from this text field.
void	restore() Restore the text field to its base text, throwing away user changes, and mark the text field as unedited.
void	restore(boolean silently) Restore the text field to its base text, throwing away user changes, and mark the text field as unedited.
protected void	restoreTabbing()
void	setBaseText(String s) Sets the text that the text field will return to when restore() is called.
void	setBaseText(String s, boolean silently) Sets the text that the text field will return to when restore() is called.
protected void	setBorder_JTextField(Border border) For subclasses of KTextField, access to JComponent.setBorder(Border).
void	setBorder(Border border) Sets the border for the text field to a new compound border with border as the outer border and an internal status border as the inside border.
void	setCaseMode(KTextField.CaseMode caseMode) Sets the current character case conversion mode of the text field to CaseMode.NO_CHANGE, CaseMode.TO_UPPER, or CaseMode.TO_LOWER.
void	setDisabledBackground(Color color) Sets the background color used to show that the text field is disabled.
void	setDocument(Document doc)
void	setEditable(boolean editable)
void	setEditableBackground(Color color) Sets the background color used to show that the text field is editable.
void	setEnabled(boolean enabled)
void	setErrorBackground(Color color) Sets the background color used to show that the text field is in an error state.
void	setErrorIcon(Icon icon) Sets the Icon used to show error conditions.
void	setErrorState(KTextField.ErrorState state) Used to set or clear the error state of the text field.
void	setMaximumLength(int maxLength) Sets the maximum length allowed for text input.
void	setMaximumLength(int maxLength, boolean checkLengthInBytes) Sets the maximum length allowed for text input while also specifying if that length should be measured in characters or in encoded bytes.
void	setMaximumLength(int maxLength, String byteEncoding) Sets the maximum length allowed for text input while also specifying a byte encoding for measuring text length in bytes.
boolean	setMaximumLengthNE(int maxLength, String byteEncoding) Same as setMaximumLength(int, String), except will not throw an exception for unsupported character encodings.
void	setModifiedTextColor(Color color) Sets the color used to show that the text field has been edited by user input.
void	setPersistentError() Sets the error state of the text field.
void	setPopupSuggestions(String[] suggestions) Displays a pop-up list of text completion choices a user can click on (or navigate to via arrow keys, selecting with the Tab key) to fill in the contents of the text field.
void	setShowModified(boolean show) Set whether the text field shows edited text in a different color from unmodified text.
void	setStandardTextColor(Color color) Sets the color used to show standard text (text which is not a suggestion, not edited).
void	setSuggestionText(String s) Sets text to be displayed when the text field is both empty and out of focus.
void	setSuggestionTextColor(Color color) Sets the color used to show suggested text.
protected void	setText_JTextField(String s) For subclasses of KTextField, access to JTextComponent.setText(String).
void	setText(String s) Sets the contents of the text field, sets the base text to which this field can be restored after user editing, and marks the field as unedited.
void	setText(String s, boolean silently) Sets the contents of the text field, sets the base text to which this field can be restored after user editing, and marks the field as unedited.
void	setTextAsIfTyped(String s) Sets the content of this text field without changing the base text which would be restored by the restore() method.
void	setTransientError() Sets the error state of the text field.
void	setTypingUpdateDelay(int delay) Sets the delay, in milliseconds, to use between the last typed-in text change and notifications of ActionListeners registered with addTypingListener(java.awt.event.ActionListener, boolean).
void	setValidCharacterPattern(String pattern) Sets which characters are allowed for input.
void	setValidCharacterPattern(String pattern, boolean caseSensitive) Sets which characters are allowed for input.
protected void	updateAppearance()
protected void	updateText(String s)
protected void	updateTextListening()
void	updateUI()

Methods inherited from class javax.swing.JTextField

actionPropertyChanged, addActionListener, configurePropertiesFromAction, createActionPropertyChangeListener, createDefaultModel, fireActionPerformed, getAccessibleContext, getAction, getActionListeners, getActions, getColumns, getColumnWidth, getHorizontalAlignment, getHorizontalVisibility, getPreferredSize, getScrollOffset, getUIClassID, isValidateRoot, paramString, postActionEvent, removeActionListener, scrollRectToVisible, setAction, setActionCommand, setColumns, setFont, setHorizontalAlignment, setScrollOffset

Methods inherited from class javax.swing.text.JTextComponent

addCaretListener, addInputMethodListener, addKeymap, copy, cut, fireCaretUpdate, getCaret, getCaretColor, getCaretListeners, getCaretPosition, getDisabledTextColor, getDocument, getDragEnabled, getDropLocation, getDropMode, getFocusAccelerator, getHighlighter, getInputMethodRequests, getKeymap, getKeymap, getMargin, getNavigationFilter, getPreferredScrollableViewportSize, getPrintable, getScrollableBlockIncrement, getScrollableTracksViewportHeight, getScrollableTracksViewportWidth, getScrollableUnitIncrement, getSelectedText, getSelectedTextColor, getSelectionColor, getSelectionEnd, getSelectionStart, getText, getToolTipText, getUI, isEditable, loadKeymap, modelToView, moveCaretPosition, paste, print, print, print, processInputMethodEvent, read, removeCaretListener, removeKeymap, replaceSelection, select, selectAll, setCaret, setCaretColor, setCaretPosition, setComponentOrientation, setDisabledTextColor, setDragEnabled, setDropMode, setFocusAccelerator, setHighlighter, setKeymap, setMargin, setNavigationFilter, setSelectedTextColor, setSelectionColor, setSelectionEnd, setSelectionStart, setUI, viewToModel, write

Methods inherited from class javax.swing.JComponent

addAncestorListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setFocusTraversalKeys, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

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

Field Detail

altIsDown

protected boolean altIsDown

baseText

protected String baseText

byteEncoding

protected String byteEncoding

caseMode

protected KTextField.CaseMode caseMode

checkLengthInBytes

protected boolean checkLengthInBytes

currentEncoder

protected CharsetEncoder currentEncoder

defaultBackground

protected Color defaultBackground

defaultBorder

protected Border defaultBorder

defaultForeground

protected Color defaultForeground

docListener

protected DocumentListener docListener

editableBackground

protected Color editableBackground

errorBackground

protected Color errorBackground

errorIcon

protected Icon errorIcon

errorState

protected KTextField.ErrorState errorState

explicitBorder

protected Border explicitBorder

explicitDisabledBackground

protected Color explicitDisabledBackground

explicitStandardTextColor

protected Color explicitStandardTextColor

focusRegainedFromPopup

protected boolean focusRegainedFromPopup

hasBeenEdited

protected boolean hasBeenEdited

ignoreDocumentChange

protected int ignoreDocumentChange

lastText

protected String lastText

leftToRight

protected boolean leftToRight

maxLength

protected int maxLength

modifiedTextColor

protected Color modifiedTextColor

navigator

protected PopupNavigator navigator

parent

protected Container parent

popup

protected JPopupMenu popup

popupMenuListener

protected PopupMenuListener popupMenuListener

popupSuggestions

protected String[] popupSuggestions

propertyChangeListener

protected PropertyChangeListener propertyChangeListener

savedForwardTraversalKeys

protected Set<AWTKeyStroke> savedForwardTraversalKeys

savedSelectionEnd

protected int savedSelectionEnd

savedSelectionStart

protected int savedSelectionStart

showModified

protected boolean showModified

suggestionShowing

protected boolean suggestionShowing

suggestionText

protected String suggestionText

suggestionTextColor

protected Color suggestionTextColor

suppressNextPopupFor

protected String suppressNextPopupFor

textCheckLength

protected int textCheckLength

textCheckPending

protected boolean textCheckPending

textCheckStart

protected int textCheckStart

textListenerHandler

protected ListenerHandler textListenerHandler

typingListenerHandler

protected ListenerHandler typingListenerHandler

typingDelay

protected DelayedAction typingDelay

validCharacterPattern

protected Pattern validCharacterPattern

DEFAULT_ERROR_ICON

public static final Icon DEFAULT_ERROR_ICON

DEFAULT_EDITABLE_BACKGROUND

public static final Color DEFAULT_EDITABLE_BACKGROUND

DEFAULT_ERROR_BACKGROUND

public static final Color DEFAULT_ERROR_BACKGROUND

DEFAULT_MODIFIED_TEXT_COLOR

public static final Color DEFAULT_MODIFIED_TEXT_COLOR

DEFAULT_SUGGESTION_TEXT_COLOR

public static final Color DEFAULT_SUGGESTION_TEXT_COLOR

DEFAULT_TYPING_UPDATE_DELAY

public static final int DEFAULT_TYPING_UPDATE_DELAY

See Also:

Constant Field Values

ICON_GAP

protected static final int ICON_GAP

See Also:

Constant Field Values

Constructor Detail

KTextField

public KTextField()

Constructs a new empty KTextField. A default model is created, the initial string is an empty string, and the number of columns is set to 0.

KTextField

public KTextField(String text)

Constructs a new KTextField initialized with the specified text. A default model is created and the number of columns is 0.

Parameters:

text - the text to be displayed, or null

KTextField

public KTextField(int columns)

Constructs a new empty KTextField with the specified number of columns. A default model is created and the initial string is an empty string.

Parameters:

columns - the number of columns to use to calculate the preferred width; if columns is set to zero, the preferred width will be whatever naturally results from the component implementation

KTextField

public KTextField(String text,
                  int columns)

Constructs a new KTextField initialized with the specified text and column width. A default model is created.

Parameters:

text - the text to be displayed, or null

columns - the number of columns to use to calculate the preferred width; if columns is set to zero, the preferred width will be whatever naturally results from the component implementation

KTextField

public KTextField(Document doc,
                  String text,
                  int columns)

Constructs a new KTextField which uses the specified text storage model, text content, and number of columns. If doc is null, a default model is created.

Parameters:

doc - the text storage to use; if this is null, a default will be provided by calling the createDefaultModel method

text - the initial string to display, or null

columns - the number of columns to use to calculate the preferred width >= 0; if columns is set to zero, the preferred width will be whatever naturally results from the component implementation

Throws:

IllegalArgumentException - if columns < 0

Method Detail

KTextFieldX

protected void KTextFieldX()

setBorder

public void setBorder(Border border)

Sets the border for the text field to a new compound border with border as the outer border and an internal status border as the inside border. If border is null, the text field's border will become the internal status border itself.

Overrides:

setBorder in class JComponent

Parameters:

border - the outermost border to be rendered for this component

setBorder_JTextField

protected final void setBorder_JTextField(Border border)

For subclasses of KTextField, access to JComponent.setBorder(Border).

Parameters:

border - the border to be rendered for this component

getUserBorder

public Border getUserBorder()

Returns the border set by the user (or by the current look and feel) for this component, rather than the compound border created by combining the user border with this component's inner status border.

Returns:

user border

setPopupSuggestions

public void setPopupSuggestions(String[] suggestions)

Displays a pop-up list of text completion choices a user can click on (or navigate to via arrow keys, selecting with the Tab key) to fill in the contents of the text field.

Parameters:

suggestions - a list of text completion choices, if null or empty causes any currently displayed pop-up list to disappear.

restoreTabbing

protected void restoreTabbing()

addNotify

public void addNotify()

Overrides:

addNotify in class JComponent

removeNotify

public void removeNotify()

Overrides:

removeNotify in class JTextComponent

getText

public String getText()

Returns the content of this text field, an empty string if the text field's Document is null or if the content is undefined.

Overrides:

getText in class JTextComponent

Returns:

the content of the text field

getText_JTextField

protected final String getText_JTextField()

For subclasses of KTextField, access to JTextComponent.getText().

Returns:

contents of text field (including suggestion text, if currently set)

isEmpty

public boolean isEmpty()

Check if the text field is empty, disregarding any suggestion text that may currently be shown.

Returns:

true if the text field is empty

isReallyEmpty

protected boolean isReallyEmpty()

Check if the text field is empty of both regular text and suggestion text.

Returns:

true if the text field is empty

setText

public void setText(String s)

Sets the contents of the text field, sets the base text to which this field can be restored after user editing, and marks the field as unedited. If the contents of the text field are changed, registered TextListener(s) will be notified of the change.

Overrides:

setText in class JTextComponent

Parameters:

s - content of text field

setText

public void setText(String s,
                    boolean silently)

Sets the contents of the text field, sets the base text to which this field can be restored after user editing, and marks the field as unedited. If the contents of the text field are changed, registered TextListener(s) will be notified of the change unless silently is true.

Parameters:

s - content of text field

silently - true if TextListener[s] should not be notified of a text change.

setText_JTextField

protected final void setText_JTextField(String s)

For subclasses of KTextField, access to JTextComponent.setText(String).

Parameters:

s - content of text field

setTextAsIfTyped

public void setTextAsIfTyped(String s)

Sets the content of this text field without changing the base text which would be restored by the restore() method. s will be filtered for invalid characters and checked against length limitations the same way typed text is checked.

Parameters:

s - content of text field

updateText

protected void updateText(String s)

broadcastTextChange

protected void broadcastTextChange()

setEnabled

public void setEnabled(boolean enabled)

Overrides:

setEnabled in class JComponent

setEditable

public void setEditable(boolean editable)

Overrides:

setEditable in class JTextComponent

getSuggestionText

public String getSuggestionText()

Returns the text which will be shown as suggested or example input when the text field is empty and doesn't have focus, or null if there is no suggested text.

Returns:

current suggested text, or null if not set

setSuggestionText

public void setSuggestionText(String s)

Sets text to be displayed when the text field is both empty and out of focus. The text will by default be displayed as light gray, but that color can be changed using setSuggestionTextColor(Color).

Parameters:

s - suggested or example text input

hasError

public boolean hasError()

Returns true if the text field is flagged as being in error.

Returns:

true if field is flagged as being in error

getErrorState

public KTextField.ErrorState getErrorState()

Returns one of the following enumerated values: ErrorState.NO_ERROR, ErrorState.TRANSIENT_ERROR, or ErrorState.PERSISTENT_ERROR, representing the error state of the text field.

Returns:

current error state

setErrorState

public void setErrorState(KTextField.ErrorState state)

Used to set or clear the error state of the text field. With default settings, an error state other than ErrorState.NO_ERROR will change the background color of the text field to pale red, and display a red stop sign icon at the trailing edge of the field (both the color and icon used can be customized). ErrorState.TRANSIENT_ERROR lasts until the user makes some change (any change) in the content of the text field. ErrorState.PERSISTENT_ERROR lasts until explicitly cleared.

Parameters:

state - ErrorState.NO_ERROR, ErrorState.TRANSIENT_ERROR, or ErrorState.PERSISTENT_ERROR

clearError

public void clearError()

Clears the error state of the text field. Equivalent to setErrorState(ErrorState.NO_ERROR).

setTransientError

public void setTransientError()

Sets the error state of the text field. Equivalent to setErrorState(ErrorState.TRANSIENT_ERROR).

setPersistentError

public void setPersistentError()

Sets the error state of the text field. Equivalent to setErrorState(ErrorState.PERSISTENT_ERROR).

getErrorIcon

public Icon getErrorIcon()

Returns the Icon currently being used to show error conditions.

Returns:

current error icon

setErrorIcon

public void setErrorIcon(Icon icon)

Sets the Icon used to show error conditions. This is preferably a 16x16 or smaller icon.

Parameters:

icon - error icon

getModifiedTextColor

public Color getModifiedTextColor()

Returns the color used to show that the text field has been edited by user input.

Returns:

color used to show modified text

setModifiedTextColor

public void setModifiedTextColor(Color color)

Sets the color used to show that the text field has been edited by user input.

Parameters:

color - color used to show modified text

getShowModified

public boolean getShowModified()

Returns true if the text field shows edited text in a different color from unmodified text.

Returns:

true if the text field shows edited text in a different color

setShowModified

public void setShowModified(boolean show)

Set whether the text field shows edited text in a different color from unmodified text.

Parameters:

show - true to show edited text in a different color

getEditableBackground

public Color getEditableBackground()

Returns the background color used to show that the text field is editable.

Returns:

background color used to show that the text field is editable

setEditableBackground

public void setEditableBackground(Color color)

Sets the background color used to show that the text field is editable.

Parameters:

color - background color used to show that the text field is editable

getErrorBackground

public Color getErrorBackground()

Returns the background color used to show that the text field is in an error state.

Returns:

background color used to show that the text field is in an error state

setErrorBackground

public void setErrorBackground(Color color)

Sets the background color used to show that the text field is in an error state.

Parameters:

color - background color used to show that the text field is in an error state

getSuggestionTextColor

public Color getSuggestionTextColor()

Returns the color used to show suggested text.

Returns:

color used to show suggested text

setSuggestionTextColor

public void setSuggestionTextColor(Color color)

Sets the color used to show suggested text.

Parameters:

color - color used to show suggested text

getDisabledBackground

public Color getDisabledBackground()

Returns the background color used to show that the text field is disabled.

Returns:

background color used to show that the text field is disabled

setDisabledBackground

public void setDisabledBackground(Color color)

Sets the background color used to show that the text field is disabled.

Parameters:

color - background color used to show that the text field is disabled

getStandardTextColor

public Color getStandardTextColor()

Returns the color used to show standard text.

Returns:

color used to show standard text

setStandardTextColor

public void setStandardTextColor(Color color)

Sets the color used to show standard text (text which is not a suggestion, not edited).

Parameters:

color - color used to show standard text

getMaximumLength

public int getMaximumLength()

Returns the maximum length allowed for text input.

Returns:

maximum length allowed for text input

getByteEncoding

public String getByteEncoding()

Returns the byte encoding (such as "UTF-8") used to measure the length of the text field in bytes.

Returns:

byte encoding used to measure the length of the text field in bytes

isCheckingEncodedLength

public boolean isCheckingEncodedLength()

Returns true if text field maximum length is being checked using encoded byte length rather than character length.

Returns:

true if maximum length checked by encoded byte length

setMaximumLength

public void setMaximumLength(int maxLength)

Sets the maximum length allowed for text input.

Parameters:

maxLength - maximum length allowed for text input

setMaximumLength

public void setMaximumLength(int maxLength,
                             boolean checkLengthInBytes)

Sets the maximum length allowed for text input while also specifying if that length should be measured in characters or in encoded bytes. The byte encoding, UTF-8 by default, will be UTF-8 or the last explicitly set encoding.

Parameters:

maxLength - maximum length allowed for text input

checkLengthInBytes - true if the length should be measured in encoded bytes

setMaximumLengthNE

public boolean setMaximumLengthNE(int maxLength,
                                  String byteEncoding)

Same as setMaximumLength(int, String), except will not throw an exception for unsupported character encodings.

Parameters:

maxLength - maximum length allowed for text input

byteEncoding - an encoding, such as "UTF-8", for translating characters into bytes, null for measuring length in characters rather than bytes.

Returns:

true if the specified byteEncoding is supported.

setMaximumLength

public void setMaximumLength(int maxLength,
                             String byteEncoding)
                      throws UnsupportedEncodingException

Sets the maximum length allowed for text input while also specifying a byte encoding for measuring text length in bytes.

Parameters:

maxLength - maximum length allowed for text input

byteEncoding - an encoding, such as "UTF-8", for translating characters into bytes, null for measuring length in characters rather than bytes.

Throws:

UnsupportedEncodingException - if byteEncoding does not represent a supported character encoding.

getMeasuredLength

public int getMeasuredLength()

Returns the current length of the text field, measured in characters or bytes, depending on which length is currently being enforced for maximum length.

Returns:

length of current text, in characters or bytes, depending on current maximum length settings.

getMeasuredLength

protected int getMeasuredLength(String s)

setBaseText

public void setBaseText(String s)

Sets the text that the text field will return to when restore() is called. If the text field has not been edited by the user, the text content will immediately change to the new text.

Parameters:

s - base text for the text field

setBaseText

public void setBaseText(String s,
                        boolean silently)

Sets the text that the text field will return to when restore() is called. If the text field has not been edited by the user, the text content will immediately change to the new text. If the text changes TextListeners will not be notified of the change if silently is true.

Parameters:

s - base text for the text field

silently - true if TextListeners should not be notified of text changes.

getHasBeenEdited

public boolean getHasBeenEdited()

Returns true if the text field has been edited, that is, if the text field's current content differs from its current base text.

Returns:

true if the text field has been edited

accept

public void accept()

Make the current content of the text field the base text for the field, and mark the text field as unedited.

restore

public void restore()

Restore the text field to its base text, throwing away user changes, and mark the text field as unedited.

restore

public void restore(boolean silently)

Restore the text field to its base text, throwing away user changes, and mark the text field as unedited. If restoration changes the content of the text field, TextListeners will not be notified if silently is true.

Parameters:

silently - true if TextListeners should not be notified of text changes.

getCaseMode

public KTextField.CaseMode getCaseMode()

Returns the current case conversion mode of the text field, one of CaseMode.NO_CHANGE, CaseMode.TO_UPPER, or CaseMode.TO_LOWER.

Returns:

current case conversion mode of the text field

setCaseMode

public void setCaseMode(KTextField.CaseMode caseMode)

Sets the current character case conversion mode of the text field to CaseMode.NO_CHANGE, CaseMode.TO_UPPER, or CaseMode.TO_LOWER. The default mode is CaseMode.NO_CHANGE. The other two modes cause character input to be converted to uppercase or lowercase, respectively.

Parameters:

caseMode - case conversion mode for the text field

setValidCharacterPattern

public void setValidCharacterPattern(String pattern)

Sets which characters are allowed for input. Allowed characters are expressed in the form of a regular expression character class, with the outer square brackets assumed. For example, to allow hexadecimal input, use the pattern "0-9A-Za-z".

Parameters:

pattern - character class pattern for allowed characters

setValidCharacterPattern

public void setValidCharacterPattern(String pattern,
                                     boolean caseSensitive)

Sets which characters are allowed for input. Allowed characters are expressed in the form of a regular expression character class, with the outer square brackets assumed. For example, to allow hexadecimal input, use the pattern "0-9A-Za-z", or "0-9A-Z" with caseSensitive set to false.

Parameters:

pattern - character class pattern for allowed characters

caseSensitive - true if the pattern is case sensitive.

processKeyEvent

protected void processKeyEvent(KeyEvent event)

Overrides:

processKeyEvent in class JComponent

isCharacterInputEvent

public static boolean isCharacterInputEvent(KeyEvent event)

Determine if event represents simple character input, as opposed to action keys, backspaces, cursor movement, etc. This function may err on the side of false negatives, causing character input to miss being filtered at the key stroke level, but there will be other opportunities for character filtering via the monitoring of document events.

Parameters:

event - event to be tested

Returns:

true if event represents simple character input

processKeyEvent_JTextField

protected final void processKeyEvent_JTextField(KeyEvent event)

For subclasses of KTextField, access to JComponent.processKeyEvent(KeyEvent).

Parameters:

event - the key event

updateTextListening

protected void updateTextListening()

checkTextChange

protected void checkTextChange(int start,
                               int length)

checkTextChangeAux

protected void checkTextChangeAux(int start,
                                  int length)

addTextListener

public void addTextListener(TextListener listener)

Adds the specified text event listener to receive text events from this text field.

Parameters:

listener - the text event listener

See Also:

removeTextListener(TextListener), TextListener

removeTextListener

public void removeTextListener(TextListener listener)

Removes the specified text event listener so that it no longer receives text events from this text field.

Parameters:

listener - the text listener

See Also:

addTextListener(TextListener)

addTypingListener

public void addTypingListener(ActionListener listener)

Add an ActionListener which will be called in response to typing changes, once changes have stopped occurring for a specified typing update delay (which defaults to 250 msec. if not explicitly set). The command string of the ActionEvent delivered to the ActionListener is the text content of the text field.

Notification will occur on the AWT event dispatch thread.

Parameters:

listener - ActionListener to add

See Also:

ActionListener, ActionEvent

addTypingListener

public void addTypingListener(ActionListener listener,
                              boolean awtNotify)

Add an ActionListener which will be called in response to typing changes, once changes have stopped occurring for a specified typing update delay (which defaults to 250 msec. if not explicitly set). The command string of the ActionEvent delivered to the ActionListener is the text content of the text field.

Notification will occur on the AWT event dispatch thread if awtNotify is true, otherwise on a non-AWT thread.

Parameters:

listener - ActionListener to add

awtNotify - true for notification to occur on the AWT event dispatch thread

See Also:

ActionListener, ActionEvent

removeTypingListener

public void removeTypingListener(ActionListener listener)

Removes the specified ActionListener so that it no longer receives typing change events from this text field.

Parameters:

listener - ActionListener to remove

See Also:

addTypingListener(ActionListener, boolean)

getTypingUpdateDelay

public int getTypingUpdateDelay()

Returns the delay, in milliseconds, used between the last typed-in text change and notifications of ActionListeners registered with addTypingListener(java.awt.event.ActionListener, boolean).

Returns:

typing update delay, in milliseconds

setTypingUpdateDelay

public void setTypingUpdateDelay(int delay)

Sets the delay, in milliseconds, to use between the last typed-in text change and notifications of ActionListeners registered with addTypingListener(java.awt.event.ActionListener, boolean).

Parameters:

delay - typing update delay, in milliseconds

setDocument

public void setDocument(Document doc)

Overrides:

setDocument in class JTextField

getLength

public int getLength()

Returns the length in characters of the current content of the text field.

Returns:

length of text content of text field, in characters

beep

protected void beep()

isValidCharacter

protected boolean isValidCharacter(char ch)

updateAppearance

protected void updateAppearance()

updateUI

public void updateUI()

Overrides:

updateUI in class JTextComponent

createOuterBorder

protected Border createOuterBorder()

getStatusBorderInsets

protected Insets getStatusBorderInsets()

paintStatusBorder

protected void paintStatusBorder(Graphics g,
                                 int x,
                                 int y,
                                 int width,
                                 int height)

refreshBorder

protected void refreshBorder()