Package swingtree

Class UIForAnyTextComponent<I,C extends JTextComponent>

java.lang.Object
swingtree.UIForAnything<I,C,JComponent>
swingtree.UIForAnySwing<I,C>
swingtree.UIForAnyTextComponent<I,C>
Type Parameters:
I - The type parameter for the instance type of this concrete class itself.
C - The type parameter for the text component type which is being built by this builder.
Direct Known Subclasses:
UIForAnyEditorPane, UIForFormattedTextField, UIForPasswordField, UIForTextArea, UIForTextField
public abstract class UIForAnyTextComponent<I,C extends JTextComponent> extends UIForAnySwing<I,C>
A SwingTree builder designed for configuring various kinds of JTextComponent instances in a fluent and declarative way. It also allows for the binding of text properties to the text component so that the text of the text component is dynamically updated whenever the value of the property changes and conversely, the value of the property is dynamically updated whenever the text of the text component changes.

Please take a look at the living swing-tree documentation where you can browse a large collection of examples demonstrating how to use the API of this class.

  • Constructor Details

    • UIForAnyTextComponent

      public UIForAnyTextComponent()

  • Method Details

    • withText

      public final I withText(String text)
      Sets the text of the wrapped TextComponent to the specified text. If the text is null an exception is thrown. Please use an empty string instead of null! When text has been inserted, the resulting caret location is determined by the implementation of the caret class.

      Note that text is not a bound property, so no PropertyChangeEvent is fired when it changes. To listen for changes to the text, register action lambdas through onTextChange(Action) or use DocumentListener directly.

      Parameters:
      text - The new text to be set for the wrapped text component type.
      Returns:
      This very builder to allow for method chaining.

    • withText

      public final I withText(sprouts.Val<String> text)
      Binds the text of the wrapped TextComponent to the specified Val property instance so that the text of the wrapped text component is dynamically updated whenever the value of the property changes.

      Note that the text of the wrapped text component is only updated if the new value is different from the old value. This is to avoid infinite feedback loops.

      Parameters:
      text - The property instance to bind the text of the wrapped text component to.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if the specified property is null.
      IllegalArgumentException - if the specified property allows null values.

    • withText

      public final I withText(sprouts.Var<String> text)
      Binds the text of the wrapped TextComponent to the specified Val property instance so that the text of the wrapped text component is dynamically updated whenever the value of the property changes.

      This method is the same as withText(Val) except that the Var property is used instead of the Val property which allows for the text of the wrapped text component to be changed by the user.

      Parameters:
      text - The property instance to bind the text of the wrapped text component to.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if the specified property is null.
      IllegalArgumentException - if the specified property allows null values.

    • _setTextSilently

      protected final void _setTextSilently(C thisComponent, String text)

    • withFont

      public final I withFont(Font font)
      Use this to set the font of the wrapped JTextComponent.
      Parameters:
      font - The font of the text which should be displayed on the text component.
      Returns:
      This builder instance, to allow for method chaining.
      Throws:
      IllegalArgumentException - if font is null.

    • withFont

      public final I withFont(sprouts.Val<Font> font)
      Use this to dynamically set the font of the wrapped JTextComponent through the provided view model property. When the font wrapped by the provided property changes, then so does the font of this text component.
      Parameters:
      font - The font property of the text which should be displayed on the text component.
      Returns:
      This builder instance, to allow for method chaining.
      Throws:
      IllegalArgumentException - if font is null.
      IllegalArgumentException - if font is a property which can wrap null.

    • isEditableIf

      public final I isEditableIf(boolean isEditable)
      Use this to modify the components' modifiability.
      Parameters:
      isEditable - The flag determining if the underlying JTextComponent should be editable or not.
      Returns:
      This very builder to allow for method chaining.

    • onContentChange

      public final I onContentChange(sprouts.Action<ComponentDelegate<JTextComponent,DocumentEvent>> action)
      Use this to register any change in the contents of the text component including both the displayed text and its attributes.
      Parameters:
      action - An action which will be executed when the text or its attributes in the underlying JTextComponent changes.
      Returns:
      This very builder to allow for method chaining.

    • onTextChange

      public final I onTextChange(sprouts.Action<ComponentDelegate<JTextComponent,DocumentEvent>> action)
      Use this to register if the text in this text component changes. This does not include style attributes like font size.
      Parameters:
      action - An action which will be executed when the text string in the underlying JTextComponent changes.
      Returns:
      This very builder to allow for method chaining.

    • _onTextChange

      protected final void _onTextChange(C thisComponent, Consumer<DocumentEvent> action)

    • onTextRemove

      public final I onTextRemove(sprouts.Action<TextRemoveDelegate> action)
      Allows you to register a user action listener which will be called whenever parts (or all) of the text in the underlying text component gets removed. This event is based on the DocumentFilter.remove(DocumentFilter.FilterBypass, int, int) method of the underlying AbstractDocument.
      Parameters:
      action - A Action lambda which will be called when parts (or all) of the text in the underlying text component gets removed.
      Returns:
      This very builder to allow for method chaining.

    • onTextInsert

      public final I onTextInsert(sprouts.Action<TextInsertDelegate> action)
      Allows you to register a user action listener which will be called whenever new text gets inserted into the underlying text component. This event is based on the DocumentFilter.insertString(DocumentFilter.FilterBypass, int, String, AttributeSet) method of the underlying AbstractDocument. Use the TextInsertDelegate that is supplied to your action to get access to the underlying text component and the text insertion details.
      Parameters:
      action - A Action lambda which will be called when new text gets inserted into the underlying text component.
      Returns:
      This very builder to allow for method chaining.

    • onTextReplace

      public final I onTextReplace(sprouts.Action<TextReplaceDelegate> action)
      This method allows you to register a user action which will be called whenever the text in the underlying text component gets replaced. This event is based on the DocumentFilter.replace(DocumentFilter.FilterBypass, int, int, String, AttributeSet) method of the underlying AbstractDocument. Use the TextReplaceDelegate that is supplied to your action to get access to the underlying text component and the text replacement details.
      Parameters:
      action - A Action lambda which will be called when the text in the underlying text component gets replaced.
      Returns:
      This very builder to allow for method chaining.