Package swingtree

Class UIForAnySwing<I,C extends JComponent>

java.lang.Object
swingtree.UIForAnything<I,C,JComponent>
swingtree.UIForAnySwing<I,C>
Type Parameters:
I - The concrete extension of the UIForAnything.
C - The type parameter for the component type wrapped by an instance of this class.
Direct Known Subclasses:
UIForAnyButton, UIForAnyScrollPane, UIForAnyTextComponent, UIForBox, UIForCombo, UIForIcon, UIForLabel, UIForList, UIForPanel, UIForPopup, UIForProgressBar, UIForSeparator, UIForSlider, UIForSpinner, UIForSplitPane, UIForSwing, UIForTabbedPane, UIForTable, UIForTableHeader, UIForToolBar
public abstract class UIForAnySwing<I,C extends JComponent> extends UIForAnything<I,C,JComponent>
A generic SwingTree builder node designed as a basis for configuring any kind of JComponent instance. This is the most generic builder type and therefore abstract super-type for almost all other builders. This builder defines nested building for anything extending the JComponent class.

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

    • UIForAnySwing

      public UIForAnySwing()

  • Method Details

    • _isUndefinedFont

      protected final boolean _isUndefinedFont(Font font)

    • _isUndefinedColor

      protected final boolean _isUndefinedColor(Color color)

    • withRepaintOn

      public final I withRepaintOn(sprouts.Observable observable)
      Use this to bind an Observable (usually from a sprouts.Event) to the Component.repaint() method of the component represented by this builder. This means that the component will be repainted whenever the source of the observable is fired or changed.
      Parameters:
      observable - The observable to which the repaint method of the component will be bound.
      Returns:
      This declarative builder instance, which enables builder-style method chaining.

    • withRepaintOn

      public final I withRepaintOn(sprouts.Observable first, sprouts.Observable second, sprouts.Observable... rest)
      This method exposes a concise way to bind multiple Observables (usually sprouts.Event instances) to the Component.repaint() method of the component represented by this builder. This means that the component will be repainted whenever the source of any one of the observables is fired or changed.
      Parameters:
      first - The first observable to which the repaint method of the component will be bound.
      second - The second observable to which the repaint method of the component will be bound.
      rest - The rest of the observables to which the repaint method of the component will be bound.
      Returns:
      This declarative builder instance, which enables builder-style method chaining.

    • withRepaintOn

      public final I withRepaintOn(sprouts.Event event)
      Allows you to bind an Event to the Component.repaint() method of the component represented by this builder.
      This means that the component will be repainted whenever the event is fired through the Event.fire() method.
      Parameters:
      event - The event to which the repaint method of the component will be bound.
      Returns:
      This declarative builder instance, which enables builder-style method chaining.

    • withRepaintOn

      public final I withRepaintOn(sprouts.Event first, sprouts.Event second, sprouts.Event... rest)
      This method exposes a concise way to bind multiple Events to the Component.repaint() method of the component represented by this builder. This means that the component will be repainted whenever any one of the events is fired through the Event.fire() method.
      Parameters:
      first - The first event to which the repaint method of the component will be bound.
      second - The second event to which the repaint method of the component will be bound.
      rest - The rest of the events to which the repaint method of the component will be bound.
      Returns:
      This declarative builder instance, which enables builder-style method chaining.

    • withRepaintOn

      public final I withRepaintOn(sprouts.Val<?> event)
      Allows you to bind a Val to the Component.repaint() method of the component represented by this builder.
      This means that the component will be repainted whenever the value of the Val changes. If the Val is a mutable Var property, then this event is usually triggered through the Var.set(Object) method.

      A typical use case is to use Var properties in the Styler of the style API exposed by withStyle(Styler), and then also pass these properties to the this withRepaintOn method to ensure that the style gets re-evaluated and then repainted.

      Parameters:
      event - The Val to which the repaint method of the component will be bound.
      Returns:
      This declarative builder instance, which enables builder-style method chaining.

    • withRepaintOn

      public final I withRepaintOn(sprouts.Val<?> first, sprouts.Val<?> second, sprouts.Val<?>... rest)
      Use this method to bind multiple Vals to the Component.repaint() method of the component represented by this builder. This means that the component will be repainted whenever the value of any one of the Vals changes. If the Val is a mutable Var property, then this event is usually triggered through the Var.set(Object) method.

      A typical use case is to use Var properties in the Styler of the style API exposed by withStyle(Styler), and then also pass these properties to the this withRepaintOn method to ensure that the style gets re-evaluated and then repainted.

      Parameters:
      first - The first Val to which the repaint method of the component will be bound.
      second - The second Val to which the repaint method of the component will be bound.
      rest - The rest of the Vals to which the repaint method of the component will be bound.
      Returns:
      This declarative builder instance, which enables builder-style method chaining.

    • id

      public final I id(String id)
      This method exposes a concise way to set an identifier for the component represented by this builder chain. In essence this is simply a delegate for the Component.setName(String) method to make it more expressive and widely recognized what is meant ("id" is shorter and makes more sense than "name" which could be confused with "title").
      Parameters:
      id - The identifier for this JComponent which will simply translate to Component.setName(String)
      Returns:
      The JComponent type which will be managed by this builder.

    • id

      public final <E extends Enum<E>> I id(E id)
      This method exposes a concise way to set an enum based identifier for the component represented by this builder chain. In essence this is simply a delegate for the Component.setName(String) method to make it more expressive and widely recognized what is meant ("id" is shorter and makes more sense than "name" which could be confused with "title").

      The enum identifier will be translated to a string using Enum.name().

      Type Parameters:
      E - The enum type.
      Parameters:
      id - The enum identifier for this JComponent which will simply translate to Component.setName(String)
      Returns:
      The JComponent type which will be managed by this builder.

    • group

      public final I group(String... groupTags)
      This method is part of the SwingTree style API, and it allows you to add this component to a style group. This is conceptually similar to CSS classes, with the difference that style groups can inherit from each other inside StyleSheets.
      Here an example of how to define styles for a style group: 
      
  new StyleSheet() {
      @Override
      protected void build() {
          add(group("A").inherits("B", "C"), it -> it
              .backgroundColor(Color.RED)
          );
          add(group("B"), it -> it
              .borderWidth(12)
          );
          add(group("C"), it -> it
              .borderWidth(16)
              .borderColor(Color.YELLOW)
          );
      }
    }

      The style sheet in the above example code can be applied to a component like so: 
      
      UI.use(new MyStyleSheet(), ()->
          UI.button("Click me").group("A")
          .onClick(it -> {...})
      );

      It is advised to use the group(Enum[]) method instead of this method, as the usage of enums for modelling group tags offers much better compile time type safety!
      Parameters:
      groupTags - The names of the style groups to which this component should be added.
      Returns:
      This very instance, which enables builder-style method chaining.

    • group

      @SafeVarargs public final <E extends Enum<E>> I group(E... groupTags)
      This method is part of the SwingTree style API, and it allows you to add this component to an enum based style group. This is conceptually similar to CSS classes, with the difference that style groups can inherit from each other inside StyleSheets.
      Here an example of how to define styles for a style group: 
      
  new StyleSheet() {
          @Override
          protected void build() {
              add(group(MyGroups.A).inherits("B", "C"), it -> it
                  .backgroundColor(Color.RED)
              );
              add(group(MyGroups.B), it -> it
                  .borderWidth(12)
              );
              add(group(MyGroups.C), it -> it
                  .borderWidth(16)
                  .borderColor(Color.YELLOW)
              );
          }
      }

      The style sheet in the above example code can be applied to a component like so: 
      
      UI.use(new MyStyleSheet(), ()->
          UI.button("Click me").group(MyGroup.A)
          .onClick(it -> {...})
      );
      Type Parameters:
      E - The enum type.
      Parameters:
      groupTags - The enum based style group to which this component should be added.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isVisibleIf

      public final I isVisibleIf(boolean isVisible)
      Make the underlying JComponent type visible or invisible depending on the supplied boolean value.
      Parameters:
      isVisible - The truth value determining if the component should be visible or not.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isVisibleIfNot

      public final I isVisibleIfNot(boolean isVisible)
      This is the inverse of isVisibleIf(boolean), and it is used to make the underlying JComponent type visible or invisible.

      If the supplied boolean value is true, the component will be invisible.
      If the supplied boolean value is false, the component will be visible.

      Parameters:
      isVisible - The truth value determining if the UI component should be visible or not.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isVisibleIf

      public final I isVisibleIf(sprouts.Val<Boolean> isVisible)
      Make the underlying JComponent type dynamically visible or invisible through the supplied Val property, which is automatically bound to the JComponent.setVisible(boolean) method of the underlying JComponent type.

      This means that when the supplied Val property changes its value, then visibility of the underlying JComponent type will be updated accordingly.

      Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.

      Parameters:
      isVisible - The truth value determining if the UI component should be visible or not wrapped in a Val.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isVisibleIfNot

      public final I isVisibleIfNot(sprouts.Val<Boolean> isVisible)
      This is the inverse of isVisibleIf(Val), and it is used to make the underlying JComponent type dynamically visible or invisible.

      This means that when the supplied Val property changes its value, then visibility of the underlying JComponent type will be updated accordingly.

      If the supplied Val property is true, the component will be invisible.
      If the supplied Val property is false, the component will be visible.

      Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.

      Parameters:
      isVisible - The truth value determining if the UI component should be visible or not wrapped in a Val.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isVisibleIf

      public final <E extends Enum<E>> I isVisibleIf(E enumValue, sprouts.Val<E> enumProperty)
      Make the underlying JComponent type dynamically visible or invisible based on the equality between the supplied enum value and enum property.

      This means that when the supplied Val property changes its value, and the new value is equal to the supplied enum value, then the underlying JComponent type will be visible, otherwise it will be invisible. Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.

      Type Parameters:
      E - The enum type.
      Parameters:
      enumValue - The enum value which, if equal to the supplied enum property, makes the UI component visible.
      enumProperty - The enum property which, if equal to the supplied enum value, makes the UI component visible.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isVisibleIfNot

      public final <E extends Enum<E>> I isVisibleIfNot(E enumValue, sprouts.Val<E> enumProperty)
      This is the inverse of isVisibleIf(Enum, Val), and it is used to make the underlying JComponent type dynamically visible or invisible.

      This means that when the supplied Val property changes its value, and the new value is equal to the supplied enum value, then the underlying JComponent type will be invisible, otherwise it will be visible. Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.

      Type Parameters:
      E - The enum type for both the supplied enum value and enum property.
      Parameters:
      enumValue - The enum value which, if equal to the supplied enum property, makes the UI component invisible.
      enumProperty - The enum property which, if equal to the supplied enum value, makes the UI component invisible.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isEnabledIf

      public final I isEnabledIf(boolean isEnabled)
      Use this to enable or disable the wrapped UI component.
      Parameters:
      isEnabled - The truth value determining if the UI component should be enabled or not.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isEnabledIfNot

      public final I isEnabledIfNot(boolean isEnabled)
      This is the inverse of isEnabledIf(boolean). Use this to disable or enable the wrapped UI component.
      Parameters:
      isEnabled - The truth value determining if the UI component should be enabled or not.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isEnabledIf

      public final I isEnabledIf(sprouts.Val<Boolean> isEnabled)
      Use this to dynamically enable or disable the wrapped UI component.
      Parameters:
      isEnabled - The truth value determining if the UI component should be enabled or not wrapped in a Val.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isEnabledIfNot

      public final I isEnabledIfNot(sprouts.Val<Boolean> isEnabled)
      This is the inverse of isEnabledIf(Val). Use this to dynamically disable or enable the wrapped UI component.
      Parameters:
      isEnabled - The truth value determining if the UI component should be enabled or not wrapped in a Val.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isEnabledIf

      public final <E extends Enum<E>> I isEnabledIf(E enumValue, sprouts.Val<E> enumProperty)
      Use this to make the wrapped UI component dynamically enabled or disabled, based on the equality between the supplied enum value and enum property.
      Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Type Parameters:
      E - The enum type for both the supplied enum value and enum property.
      Parameters:
      enumValue - The enum value which, if equal to the supplied enum property, makes the UI component enabled.
      enumProperty - The enum property which, if equal to the supplied enum value, makes the UI component enabled.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isEnabledIfNot

      public final <E extends Enum<E>> I isEnabledIfNot(E enumValue, sprouts.Val<E> enumProperty)
      This is the inverse of isEnabledIf(Enum, Val). Use this to make the wrapped UI component dynamically disabled or enabled, based on the equality between the supplied enum value and enum property.
      Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Type Parameters:
      E - The enum type for both the supplied enum value and enum property.
      Parameters:
      enumValue - The enum value which, if equal to the supplied enum property, makes the UI component disabled.
      enumProperty - The enum property which, if equal to the supplied enum value, makes the UI component disabled.
      Returns:
      This very instance, which enables builder-style method chaining.

    • _setEnabled

      protected void _setEnabled(C c, boolean isEnabled)

    • makeFocused

      public final I makeFocused()
      Use this to make the wrapped UI component grab the input focus.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isFocusableIf

      public final I isFocusableIf(boolean isFocusable)
      Use this to make the wrapped UI component focusable.
      Parameters:
      isFocusable - The truth value determining if the UI component should be focusable or not.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isFocusableIf

      public final I isFocusableIf(sprouts.Val<Boolean> isFocusable)
      Use this to dynamically make the wrapped UI component focusable. This is useful if you want to make a component focusable only if a certain condition is met.
      Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      isFocusable - The truth value determining if the UI component should be focusable or not wrapped in a Val.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isFocusableIfNot

      public final I isFocusableIfNot(boolean notFocusable)
      Use this to make the wrapped UI component focusable if a certain condition is not met.
      Parameters:
      notFocusable - The truth value determining if the UI component should be focusable or not. If false, the component will be focusable.
      Returns:
      This very instance, which enables builder-style method chaining.

    • isFocusableIfNot

      public final I isFocusableIfNot(sprouts.Val<Boolean> isFocusable)
      Use this to dynamically make the wrapped UI component focusable. This is useful if you want to make a component focusable only if a certain condition is met.
      Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      isFocusable - The truth value determining if the UI component should be focusable or not, wrapped in a Val.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if the supplied isFocusable is null.

    • isFocusableIf

      public final <E extends Enum<E>> I isFocusableIf(E enumValue, sprouts.Val<E> enumProperty)
      Use this to make the wrapped UI component dynamically focusable or non-focusable based on the equality between the supplied enum value and enum property.
      Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Type Parameters:
      E - The enum type for both the supplied enum value and enum property.
      Parameters:
      enumValue - The enum value which, if equal to the supplied enum property, makes the UI component focusable.
      enumProperty - The enum property which, if equal to the supplied enum value, makes the UI component focusable.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if the supplied enumValue or enumProperty is null.

    • isFocusableIfNot

      public final <E extends Enum<E>> I isFocusableIfNot(E enumValue, sprouts.Val<E> enumProperty)
      This is the inverse of isFocusableIf(Enum, Val). Use this to make the wrapped UI component dynamically focusable or non-focusable based on the equality between the supplied enum value and enum property.
      Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Type Parameters:
      E - The enum type for both the supplied enum value and enum property.
      Parameters:
      enumValue - The enum value which, if equal to the supplied enum property, makes the UI component non-focusable.
      enumProperty - The enum property which, if equal to the supplied enum value, makes the UI component non-focusable.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - if the supplied enumValue or enumProperty is null.

    • makeOpaque

      @Deprecated public final I makeOpaque()
      Deprecated.
      SwingTree considers the opaqueness a property which emerges from the style configuration of the component. Therefore, it is not recommended to set the opaqueness directly. Instead, use the withBackground(Color) method to set the style of the component so that it becomes opaque.
      Use this to make the wrapped UI component opaque. This is the inverse of makeNonOpaque().
      Returns:
      This very instance, which enables builder-style method chaining.

    • makeNonOpaque

      @Deprecated public final I makeNonOpaque()
      Deprecated.
      Use withBackground(Color) instead, by passing it the UI.Color.TRANSPARENT constant.
      Alternatively, you may use the UIForAnything.peek(Peeker) method to peek into the builder's component and set the flag directly.
      Use this to make the wrapped UI component transparent. This is the inverse of makeOpaque().
      Returns:
      This very instance, which enables builder-style method chaining.

    • isValidIf

      public final I isValidIf(UIVerifier<C> verifier)
      This allows you to register validation logic for the wrapped UI component. Although the delegate exposed to the UIVerifier lambda indirectly exposes you to the UIs state, you should not access the UI directly from within the lambda, but modify the properties inside your view model instead.
      Parameters:
      verifier - The validation logic provided by your view model.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withProperty

      public final I withProperty(String key, String value)
      Adds String key/value "client property" pairs to the wrapped component.

      The arguments will be passed to JComponent.putClientProperty(Object, Object) which accesses a small per-instance hashtable. Callers can use get/putClientProperty to annotate components that were created by another module. For example, a layout manager might store per child constraints this way.
      This is in essence a more convenient way than the alternative usage pattern involving the UIForAnything.peek(Peeker) method to peek into the builder's component like so: 

      
     UI.button()
     .peek( button -> button.putClientProperty("key", "value") );
      Parameters:
      key - the new client property key which may be used for styles or layout managers.
      value - the new client property value.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withBorder

      public final I withBorder(Border border)
      Use this to attach a border to the wrapped component.
      Parameters:
      border - The Border which should be set for the wrapped component.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withBorder

      @Deprecated public final I withBorder(sprouts.Val<Border> border)
      Deprecated.
      Because changing the Border of a component dynamically after the component was initialized through the declarative SwingTree API, causes issues with the style engine of a component. (Which itself is based on using a custom border for style rendering)
      Use this to dynamically attach a border to the wrapped component.
      Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      border - The Border which should be set for the wrapped component wrapped in a Val.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withEmptyBorder

      public final I withEmptyBorder(int top, int left, int bottom, int right)
      Use this to define an empty Border with the provided insets.
      Parameters:
      top - The top inset.
      left - The left inset.
      bottom - The bottom inset.
      right - The right inset.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withEmptyBorderTitled

      public final I withEmptyBorderTitled(String title, int top, int left, int bottom, int right)
      Use this to define a titled empty Border with the provided insets.
      Parameters:
      title - The title of the border.
      top - The top inset.
      left - The left inset.
      bottom - The bottom inset.
      right - The right inset.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withEmptyBorderTitled

      public final I withEmptyBorderTitled(sprouts.Val<String> title, int top, int left, int bottom, int right)
      Use this to define a titled empty Border with the provided insets and where the title is bound to a Val.
      Parameters:
      title - The title of the border wrapped in a Val, which will update the border title dynamically when changed.
      top - The top inset.
      left - The left inset.
      bottom - The bottom inset.
      right - The right inset.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withEmptyBorder

      public final I withEmptyBorder(int topBottom, int leftRight)
      Use this to define an empty Border with the provided insets.
      Parameters:
      topBottom - The top and bottom insets.
      leftRight - The left and right insets.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withEmptyBorderTitled

      public final I withEmptyBorderTitled(String title, int topBottom, int leftRight)
      Use this to define a titled empty Border with the provided insets.
      Parameters:
      title - The title of the border.
      topBottom - The top and bottom insets.
      leftRight - The left and right insets.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withEmptyBorderTitled

      public final I withEmptyBorderTitled(sprouts.Val<String> title, int topBottom, int leftRight)
      Use this to define a titled empty Border with the provided insets and where the title is bound to a Val.
      Parameters:
      title - The title of the border wrapped in a Val. When the value changes, the border title will be updated.
      topBottom - The top and bottom insets.
      leftRight - The left and right insets.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withEmptyBorder

      public final I withEmptyBorder(int all)
      Use this to define an empty Border with the provided insets.
      Parameters:
      all - The insets for all sides.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withEmptyBorder

      public final I withEmptyBorder(sprouts.Val<Integer> all)
      Creates an empty and un-titled Border with the provided insets property bound to all insets of said border.

      An empty and un-titled Border is basically just a way to add some space around the component. It is not visible by default.

      Parameters:
      all - The insets for all sides.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withEmptyBorderTitled

      public final I withEmptyBorderTitled(String title, int all)
      Use this to define a titled empty Border with the provided insets.
      Parameters:
      title - The title of the border.
      all - The insets for all sides.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withEmptyBorderTitled

      public final I withEmptyBorderTitled(sprouts.Val<String> title, int all)
      Creates a titled empty border bound to a String property and the provided insets.
      Parameters:
      title - The title of the border in the form of a Val property.
      all - The insets size for all sides.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withEmptyBorderTitled

      public final I withEmptyBorderTitled(String title)
      Use this to define an empty Border with a title and a default insets size of 5.
      Parameters:
      title - The title of the border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withEmptyBorderTitled

      public final I withEmptyBorderTitled(sprouts.Val<String> title)
      Creates a titled empty border bound to a String property and a default insets size of 5.
      Parameters:
      title - The title of the border in the form of a Val property.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withLineBorder

      public final I withLineBorder(Color color, int thickness)
      Use this to define a line Border with the provided color and insets.
      Parameters:
      color - The color of the line border.
      thickness - The thickness of the line border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withLineBorder

      public final I withLineBorder(sprouts.Val<Color> color, int thickness)
      Creates a line border bound to a Color property. When the color changes, the border will be updated with the new color.
      Parameters:
      color - The color of the border in the form of a Val property.
      thickness - The thickness of the line border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withLineBorderTitled

      public final I withLineBorderTitled(String title, Color color, int thickness)
      Use this to define a titled line Border with the provided color and insets.
      Parameters:
      title - The title of the border.
      color - The color of the line border.
      thickness - The thickness of the line border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withLineBorderTitled

      public final I withLineBorderTitled(sprouts.Val<String> title, Color color, int thickness)
      Creates a titled line border bound to a String property.
      Parameters:
      title - The title property of the border which will update the border when the value changes.
      color - The color of the border.
      thickness - The thickness of the line border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withLineBorderTitled

      public final I withLineBorderTitled(sprouts.Val<String> title, sprouts.Val<Color> color, int thickness)
      Creates a titled line border bound to a String property and a Color property. When any of the properties change, the border will be updated with the new values.
      Parameters:
      title - The title property of the border which will update the border when the value changes.
      color - The color property of the border which will update the border when the value changes.
      thickness - The thickness of the line border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withLineBorder

      public final I withLineBorder(Color color)
      Use this to define a line Border with the provided color and a default thickness of 1.
      Parameters:
      color - The color of the border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withLineBorderTitled

      public final I withLineBorderTitled(String title, Color color)
      Use this to define a titled line Border with the provided color and a default thickness of 1.
      Parameters:
      title - The title of the border.
      color - The color of the border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withRoundedLineBorder

      public final I withRoundedLineBorder(Color color, int thickness)
      Use this to attach a rounded line Border with the provided color and insets to the JComponent.
      Parameters:
      color - The color of the border.
      thickness - The thickness of the border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withRoundedLineBorderTitled

      public final I withRoundedLineBorderTitled(String title, Color color, int thickness)
      Use this to attach a titled rounded line Border with the provided color and insets to the JComponent.
      Parameters:
      title - The title of the border.
      color - The color of the border.
      thickness - The thickness of the border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withRoundedLineBorderTitled

      public final I withRoundedLineBorderTitled(sprouts.Val<String> title, Color color, int thickness)
      Creates a titled rounded line Border with the provided color and insets for this JComponent and binds the border to the provided title property. When the title property changes, the border will be updated with the new value.
      Parameters:
      title - The title property of the border which will update the border when the value changes.
      color - The color of the border.
      thickness - The thickness of the border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withRoundedLineBorderTitled

      public final I withRoundedLineBorderTitled(sprouts.Val<String> title, sprouts.Val<Color> color, int thickness)
      Creates a titled rounded line Border with the provided color and insets for this JComponent and binds the border to the provided title and color properties. When the title or color properties change, then the border will be updated with the new values.
      Parameters:
      title - The title property of the border which will update the border when the value changes.
      color - The color property of the border which will update the border when the value changes.
      thickness - The thickness of the border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withRoundedLineBorder

      public final I withRoundedLineBorder(Color color)
      Use this to attach a rounded line Border with the provided color and a default thickness of 1 to the JComponent.
      Parameters:
      color - The color of the border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withRoundedLineBorder

      public final I withRoundedLineBorder(sprouts.Val<Color> color, int thickness)
      Use this to attach a titled rounded line Border with the provided color property and a custom thickness to the JComponent.
      Parameters:
      color - The color of the border.
      thickness - The thickness of the border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withRoundedLineBorderTitled

      public final I withRoundedLineBorderTitled(String title, Color color)
      Use this to attach a titled rounded line Border with the provided title, color and a default thickness of 1 to the JComponent.
      Parameters:
      title - The title of the border.
      color - The color of the border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withRoundedLineBorderTitled

      public final I withRoundedLineBorderTitled(sprouts.Val<String> title, sprouts.Val<Color> color)
      Use this to attach a titled rounded line Border with the provided title and color to the JComponent, as well as a default thickness of 1.
      Parameters:
      title - The title property of the border, which will update the border when the property changes.
      color - The color property of the border, which will update the border when the property changes.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withRoundedLineBorder

      public final I withRoundedLineBorder()
      Use this to attach a rounded black line Border with a thickness of 1 to the JComponent.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withRoundedLineBorderTitled

      public final I withRoundedLineBorderTitled(String title)
      Use this to attach a titled rounded black line Border with a thickness of 1 to the JComponent.
      Parameters:
      title - The title of the border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withRoundedLineBorderTitled

      public final I withRoundedLineBorderTitled(sprouts.Val<String> title)
      Creates a titled rounded black line Border with a thickness of 1 to the JComponent and binds it to the provided title property. When the property changes, the border will be updated.
      Parameters:
      title - The title property of the border, which will update the border when the property changes.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withMatteBorder

      public final I withMatteBorder(Color color, int top, int left, int bottom, int right)
      Use this to attach a MatteBorder with the provided color and insets to the JComponent.
      Parameters:
      color - The color of the border.
      top - The top inset.
      left - The left inset.
      bottom - The bottom inset.
      right - The right inset.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withMatteBorderTitled

      public final I withMatteBorderTitled(String title, Color color, int top, int left, int bottom, int right)
      Use this to attach a titled MatteBorder with the provided color and insets to the JComponent.
      Parameters:
      title - The title of the border.
      color - The color of the border.
      top - The top inset.
      left - The left inset.
      bottom - The bottom inset.
      right - The right inset.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withMatteBorder

      public final I withMatteBorder(Color color, int topBottom, int leftRight)
      Use this to attach a MatteBorder with the provided color and insets to the JComponent.
      Parameters:
      color - The color of the border.
      topBottom - The top and bottom insets.
      leftRight - The left and right insets.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withMatteBorderTitled

      public final I withMatteBorderTitled(String title, Color color, int topBottom, int leftRight)
      Use this to attach a titled MatteBorder with the provided color and insets to the JComponent.
      Parameters:
      title - The title of the border.
      color - The color of the border.
      topBottom - The top and bottom insets.
      leftRight - The left and right insets.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withMatteBorder

      public final I withMatteBorder(Color color, int all)
      Use this to attach a MatteBorder with the provided color and insets to the JComponent.
      Parameters:
      color - The color of the border.
      all - The insets for all sides.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withMatteBorderTitled

      public final I withMatteBorderTitled(String title, Color color, int all)
      Use this to attach a titled MatteBorder with the provided color and insets to the JComponent.
      Parameters:
      title - The title of the border.
      color - The color of the border.
      all - The insets for all sides.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withCompoundBorder

      public final I withCompoundBorder(Border first, Border second)
      Use this to attach a CompoundBorder with the provided borders to the JComponent.
      Parameters:
      first - The first border.
      second - The second border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withCompoundBorderTitled

      public final I withCompoundBorderTitled(String title, Border first, Border second)
      Use this to attach a titled CompoundBorder with the provided borders to the JComponent.
      Parameters:
      title - The title of the border.
      first - The first border.
      second - The second border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withBorderTitled

      public final I withBorderTitled(String title)
      Use this to attach a TitledBorder with the provided title.
      Parameters:
      title - The title of the border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withBorderTitled

      public final I withBorderTitled(sprouts.Val<String> title)
      Use this to attach a TitledBorder with the provided title property dynamically setting the title String.
      Parameters:
      title - The title property for the border.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withCursor

      public final I withCursor(UI.Cursor type)
      Use this set the cursor type which should be displayed when hovering over the UI component wrapped by this builder.
      Here an example of how to use this method: 
      
      UI.button("Click me!").withCursor(UI.Cursor.HAND);
      Parameters:
      type - The UI.Cursor type defined by a simple enum exposed by this API.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withCursor

      public final I withCursor(sprouts.Val<UI.Cursor> type)
      Use this to dynamically set the cursor type which should be displayed when hovering over the UI component wrapped by this builder.
      Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      type - The UI.Cursor type defined by a simple enum exposed by this API wrapped in a Val.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withCursorIf

      public final I withCursorIf(sprouts.Val<Boolean> condition, UI.Cursor type)
      Use this to set the cursor type which should be displayed when hovering over the UI component wrapped by this builder based on boolean property determining if the provided cursor should be set ot not.
      Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      condition - The boolean property determining if the provided cursor should be set ot not.
      type - The UI.Cursor type defined by a simple enum exposed by this API wrapped in a Val.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withCursorIf

      public final I withCursorIf(sprouts.Val<Boolean> condition, sprouts.Val<UI.Cursor> type)
      Use this to dynamically set the cursor type which should be displayed when hovering over the UI component wrapped by this builder based on boolean property determining if the provided cursor should be set ot not.
      Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      condition - The boolean property determining if the provided cursor should be set ot not.
      type - The UI.Cursor type property defined by a simple enum exposed by this API.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withLayout

      public final I withLayout(LayoutManager layout)
      Use this to set the LayoutManager of the component wrapped by this builder.
      This is in essence a more convenient way than the alternative usage pattern involving the UIForAnything.peek(Peeker) method to peek into the builder's component like so: 
      
      UI.panel()
      .peek( panel -> panel.setLayout(new FavouriteLayoutManager()) );
      Parameters:
      layout - The LayoutManager which should be supplied to the wrapped component.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withFlowLayout

      public final I withFlowLayout()
      Use this to set a FlowLayout for the component wrapped by this builder.
      This is in essence a more convenient way than the alternative usage pattern involving the UIForAnything.peek(Peeker) method to peek into the builder's component like so: 
      
      UI.panel()
      .peek( panel -> panel.setLayout(new FlowLayout()) );
      Returns:
      This very instance, which enables builder-style method chaining.

    • withFlowLayout

      public final I withFlowLayout(UI.HorizontalAlignment alignment)
      Use this to set a FlowLayout for the component wrapped by this builder.
      This is in essence a more convenient way than the alternative usage pattern involving the UIForAnything.peek(Peeker) method to peek into the builder's component like so: 
      
      UI.panel()
      .peek( panel -> panel.setLayout(new FlowLayout(alignment.forFlowLayout())) );
      Parameters:
      alignment - The alignment of the layout.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withFlowLayout

      public final I withFlowLayout(UI.HorizontalAlignment alignment, int hgap, int vgap)
      Use this to set a FlowLayout for the component wrapped by this builder.
      This is in essence a more convenient way than the alternative usage pattern involving the UIForAnything.peek(Peeker) method to peek into the builder's component like so: 
      
      UI.panel()
      .peek( panel -> panel.setLayout(new FlowLayout(alignment.forFlowLayout(), hgap, vgap)) );
      Parameters:
      alignment - The alignment of the layout.
      hgap - The horizontal gap between components.
      vgap - The vertical gap between components.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withGridLayout

      public final I withGridLayout()
      Use this to set a GridLayout for the component wrapped by this builder.
      This is in essence a more convenient way than the alternative usage pattern involving the UIForAnything.peek(Peeker) method to peek into the builder's component like so: 
      
      UI.panel()
      .peek( panel -> panel.setLayout(new GridLayout()) );
      Returns:
      This very instance, which enables builder-style method chaining.

    • withGridBagLayout

      public final I withGridBagLayout()
      Use this to set a new GridBagLayout for the component wrapped by this builder.
      This is in essence a more convenient way than the alternative usage pattern involving the UIForAnything.peek(Peeker) method to peek into the builder's component like so: 
      
      UI.panel()
      .peek( panel -> panel.setLayout(new GridBagLayout()) );
      ...or specifying the layout manager like so: 
      
    UI.panel().withLayout( new GridBagLayout() );
      Returns:
      This very instance, which enables builder-style method chaining.

    • withGridLayout

      public final I withGridLayout(int rows, int cols)
      Use this to set a GridLayout for the component wrapped by this builder.
      This is in essence a more convenient way than the alternative usage pattern involving the UIForAnything.peek(Peeker) method to peek into the builder's component like so: 
      
      UI.panel()
      .peek( panel -> panel.setLayout(new GridLayout(rows, cols)) );
      Parameters:
      rows - The number of rows in the grid.
      cols - The number of columns in the grid.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withGridLayout

      public final I withGridLayout(int rows, int cols, int hgap, int vgap)
      Use this to set a GridLayout for the component wrapped by this builder.
      This is in essence a more convenient way than the alternative usage pattern involving the UIForAnything.peek(Peeker) method to peek into the builder's component like so: 
      
      UI.panel()
      .peek( panel -> panel.setLayout(new GridLayout(rows, cols, hgap, vgap)) );
      Parameters:
      rows - The number of rows in the grid.
      cols - The number of columns in the grid.
      hgap - The horizontal gap between cells.
      vgap - The vertical gap between cells.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withBoxLayout

      public final I withBoxLayout(UI.Axis axis)
      Use this to set a BoxLayout for the component wrapped by this builder.
      This is in essence a more convenient way than the alternative usage pattern involving the UIForAnything.peek(Peeker) method to peek into the builder's component like so: 
      
      UI.panel()
      .peek( panel -> panel.setLayout(new BoxLayout(panel, axis.forBoxLayout())) );
      Parameters:
      axis - The axis for the box layout.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - If the provided axis is null.
      See Also:

    • withLayout

      public final I withLayout(String attr)
      This creates a MigLayout for the component wrapped by this UI builder, based on the provided layout-constraints in the form of a simple string which is parsed by the ConstraintParser class into LC and AC instances. (also see withLayout(LC, AC, AC))

      A typical usage pattern would be like so: 
      
    UI.of(new MyCustomPanel())
    .withLayout("fill wrap 2");
    .add( UI.button("Name:") )
    .add( UI.textArea() )
    .add(...)
    ...
      In this example a new MigLayout is created which will wrap the components in the layout grid after 2 columns and fill the entire available space of the parent container.
      Note that if not explicitly specified, the default hidemode will be set to 2, which means that when a component is hidden, it will not take up any space and the gaps around it will be collapsed.
      Here an overview of the available hidemode values:
      • 0:
        Invisible components will be handled exactly as if they were visible.
      • 1:
        The size of the component (if invisible) will be set to 0, 0.
      • 2 (SwingTree default):
        The size of the component (if invisible) will be set to 0, 0 and the gaps will also be set to 0 around it.
      • 3:
        Invisible components will not participate in the layout at all and it will for instance not take up a grid cell.
      Parameters:
      attr - The constraints concerning the entire layout. Passing null will result in an exception, use an empty string instead.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - If any of the arguments are null.
      See Also:

    • withLayout

      public final I withLayout(net.miginfocom.layout.LC attr)
      Creates a new MigLayout for the component wrapped by this UI builder, based on the provided layout constraints in the form of a LC instance, which is a builder for the layout constraints.
      Parameters:
      attr - A string defining the constraints concerning the entire layout.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - If any of the arguments are null.
      See Also:

    • withLayout

      public final I withLayout(LayoutConstraint attr)
      Creates a new MigLayout for the component wrapped by this UI builder, based on the provided layout constraints in the form of a LayoutConstraint instance, which is an immutable string wrapper for the layout constraints. Instances of this are usually obtained from the UI namespace like UILayoutConstants.FILL or UILayoutConstants.FILL_X...
      Parameters:
      attr - Essentially an immutable string wrapper defining the mig layout.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - If any of the arguments are null.

    • withLayout

      public final I withLayout(String attr, String colConstrains)
      This creates a MigLayout for the component wrapped by this UI builder based on the provided layout constraints in the form of a string.
      Parameters:
      attr - A string defining constraints for the entire layout.
      colConstrains - The layout constraints for the columns int the MigLayout instance.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - If any of the arguments are null.
      See Also:

    • withLayout

      public final I withLayout(net.miginfocom.layout.LC attr, net.miginfocom.layout.AC colConstrains)
      This creates a MigLayout for the component wrapped by this UI builder based on the provided layout constraints in the form of a LC instance and column constraints in the form of a AC instance.
      Parameters:
      attr - The constraints for the layout, a LC instance.
      colConstrains - The column layout for the MigLayout instance as a AC instance.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - If any of the arguments are null.
      See Also:

    • withLayout

      public final I withLayout(net.miginfocom.layout.LC attr, String colConstrains)
      This creates a MigLayout for the component wrapped by this UI builder based on the provided layout constraints in the form of a LC instance and column constraints in the form of a simple string.
      Parameters:
      attr - The constraints for the layout, a LC instance.
      colConstrains - The column layout for the MigLayout instance as a simple string.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - If any of the arguments are null.
      See Also:

    • withLayout

      public final I withLayout(net.miginfocom.layout.LC attr, String colConstrains, String rowConstraints)
      This creates a MigLayout for the component wrapped by this UI builder based on the provided layout constraints in the form of a LC instance and column and row constraints in the form of a simple string.
      Parameters:
      attr - The constraints for the layout, a LC instance.
      colConstrains - The column layout for the MigLayout instance as a simple string.
      rowConstraints - The row layout for the MigLayout instance as a simple string.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - If any of the arguments are null.
      See Also:

    • withLayout

      public final I withLayout(LayoutConstraint attr, String colConstrains)
      Takes the supplied layout constraints and column constraints uses them to construct a new MigLayout for the component wrapped by this UI builder.
      Parameters:
      attr - The constraints for the layout.
      colConstrains - The column layout for the MigLayout instance.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - If any of the arguments are null.
      See Also:

    • withLayout

      public final I withLayout(LayoutConstraint attr, String colConstrains, String rowConstraints)
      This creates a MigLayout for the component wrapped by this UI builder.
      Parameters:
      attr - The constraints for the layout in the form of a LayoutConstraint instance.
      colConstrains - The column layout for the MigLayout instance.
      rowConstraints - The row layout for the MigLayout instance.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withLayout

      public final I withLayout(String constraints, String colConstrains, String rowConstraints)
      This creates a MigLayout for the component wrapped by this UI builder, based on the provided layout-, column- and row-constraints in the form of simple strings, which are parsed by the ConstraintParser class into LC and AC instances. (also see withLayout(LC, AC, AC))

      A typical usage pattern would be like so: 
      
    UI.of(new MyCustomPanel())
    .withLayout("wrap 2", "[]6[]", "[]8[]");
    .add( UI.label("Name:") )
    .add( UI.textField() )
    .add(...)
    ...
      In this example a new MigLayout is created which will wrap the components in the layout grid after 2 columns, where the 2 columns are separated by a 6 pixel gap and the rows are separated by an 8 pixel gap.

      Note that if not explicitly specified, the default hidemode will be set to 2, which means that when a component is hidden, it will not take up any space and the gaps around it will be collapsed.
      Here an overview of the available hidemode values:
      • 0:
        Invisible components will be handled exactly as if they were visible.
      • 1:
        The size of the component (if invisible) will be set to 0, 0.
      • 2 (SwingTree default):
        The size of the component (if invisible) will be set to 0, 0 and the gaps will also be set to 0 around it.
      • 3:
        Invisible components will not participate in the layout at all and it will for instance not take up a grid cell.
      Parameters:
      constraints - The constraints concerning the entire layout. Passing null will result in an exception, use an empty string instead.
      colConstrains - The column layout for the MigLayout instance, which concern the columns in the layout grid. Passing null will result in an exception, use an empty string instead.
      rowConstraints - The row layout for the MigLayout instance, which concern the rows in the layout grid. Passing null will result in an exception, use an empty string instead.
      Returns:
      This very instance, which enables builder-style method chaining.
      Throws:
      IllegalArgumentException - If any of the arguments are null.
      See Also:

    • withLayout

      public final I withLayout(@Nullable net.miginfocom.layout.LC attr, @Nullable net.miginfocom.layout.AC colConstrains, @Nullable net.miginfocom.layout.AC rowConstraints)
      This creates a MigLayout for the component wrapped by this UI builder.
      Parameters:
      attr - The constraints for the layout.
      colConstrains - The column layout for the MigLayout instance.
      rowConstraints - The row layout for the MigLayout instance.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withTooltip

      public final I withTooltip(String tooltip)
      Use this to set a helpful tool tip text for this UI component. The tool tip text will be displayed when the mouse hovers on the UI component for some time.
      This is in essence a convenience method, which avoid having to expose the underlying component through the UIForAnything.peek(Peeker) method like so: 
      
      UI.button("Click Me")
      .peek( button -> button.setToolTipText("Can be clicked!") );
      Parameters:
      tooltip - The tool tip text which should be set for the UI component.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withTooltip

      public final I withTooltip(sprouts.Val<String> tip)
      Use this to bind to a Val containing a tooltip string. This is a convenience method, which would be equivalent to: 
      
      UI.button("Click Me")
      .peek( button -> {
          tip.onSetItem(JButton::setToolTipText);
          button.setToolTipText(tip.get());
      });

      Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      tip - The tooltip which should be displayed when hovering over the tab header.
      Returns:
      A new Tab instance with the provided argument, which enables builder-style method chaining.

    • withBackground

      public final I withBackground(Color color)
      Use this to set the background color of the UI component wrapped by this builder.
      This is in essence a convenience method, which avoid having to expose the underlying component through the UIForAnything.peek(Peeker) method like so: 
      
      UI.label("Something")
      .peek( label -> label.setBackground(Color.CYAN) );
      Parameters:
      color - The background color which should be set for the UI component.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withBackgroundColor

      public final I withBackgroundColor(String color)
      Use this to set the background color of the UI component of this declarative builder using a color String. The supplied String is parsed to a UI.Color through the UIFactoryMethods.color(String) method.
      This is in essence a convenience method, which avoid having to expose the underlying component through the UIForAnything.peek(Peeker) method like so: 
      
      UI.label("Something")
      .peek( label -> label.setBackground(UI.color("cyan")) );
      Parameters:
      color - A color string which should be parsed to a UI.Color instance and then set as the background color of the UI component.
      Returns:
      A new reference to this type of builder, to allow for fluent method chaining.

    • _setBackground

      protected void _setBackground(JComponent thisComponent, Color color)

    • withBackground

      public final I withBackground(sprouts.Val<Color> bg)
      Use this to bind to a Val containing a background color. This is a convenience method, which would be equivalent to: 
      
      UI.button("Click Me")
      .peek( button -> {
          bg.onSetItem(JButton::setBackground);
          button.setBackground(bg.get());
      });

      Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      bg - The background color which should be set for the UI component wrapped by a Val.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withBackgroundIf

      public final I withBackgroundIf(sprouts.Val<Boolean> condition, Color colorIfTrue)
      Use this to bind to a background color which will be set dynamically based on a boolean property. Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      condition - The condition property which determines whether the background color should be set or not.
      colorIfTrue - The background color which should be set for the UI component.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withBackgroundIf

      public final I withBackgroundIf(sprouts.Val<Boolean> condition, sprouts.Val<Color> color)
      Use this to dynamically bind to a background color which will be set dynamically based on a boolean property. Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      condition - The condition property which determines whether the background color should be set or not.
      color - The background color property which should be set for the UI component.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withBackgroundIf

      public final I withBackgroundIf(sprouts.Val<Boolean> condition, Color colorIfTrue, Color colorIfFalse)
      Use this to bind to 2 colors to the background of the component which sre set based on the value of a boolean property. Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      condition - The condition property which determines whether the background color should be set or not.
      colorIfTrue - The background color which should be set for the UI component.
      colorIfFalse - The background color which should be set for the UI component.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withBackgroundIf

      public final I withBackgroundIf(sprouts.Val<Boolean> condition, sprouts.Val<Color> colorIfTrue, sprouts.Val<Color> colorIfFalse)
      Use this to bind to 2 color properties to the background of the component which sre set based on the value of a boolean property. Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      condition - The condition property which determines whether the background color should be set or not.
      colorIfTrue - The background color which should be set for the UI component.
      colorIfFalse - The background color which should be set for the UI component.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withStyle

      public final I withStyle(Styler<C> styler)
      Allows you to configure how the component wrapped by this builder looks and behaves, by passing a Styler lambda to this method which receiving a ComponentStyleDelegate and returns an updated version with the desired style rules applied.

      Here a typical example of how to style a button using the style API: 

      
        UI.button("Click Me!")
        .withStyle( it -> it
            .borderColor(Color.CYAN)
            .borderWidthAt(Edge.BOTTOM, 3)
            .borderRadius(10)
        )

      Here the it variable is the ComponentStyleDelegate which exposes an extensive API for configuring how a particular component looks and behaves.

      If you want to define style rules for an entire GUI or a part of it, take a look at the StyleSheet class, which exposes an API for defining style rules similar to CSS but based on declarative source code instead of a text file.

      Parameters:
      styler - A Styler lambda can define a set of style rules for the component wrapped by this builder by receiving a ComponentStyleDelegate and returning an updated version with the desired style rules applied.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withTransitionalStyle

      public final I withTransitionalStyle(sprouts.Val<Boolean> transitionToggle, LifeTime transitionLifeTime, AnimatedStyler<C> styler)
      Here an example demonstrating how a transitional style can be applied to make a border which can transition between 2 colors based on a boolean property: 
      
      UI.button("Click Me!")
      .withTransitionalStyle(vm.isError(), LifeTime.of(1, TimeUnit.SECONDS), (state, it) -> it
          .backgroundColor(Color.CYAN)
          .border(3, new Color((int)(state.progress() * 255), 0, 0))
      )
      Parameters:
      transitionToggle - The boolean Val property which determines the state to which the style should transition. When the value of this property is true, the style will transition to a AnimationStatus.progress() of 1.0 over the provided LifeTime. And when the value of this property is false, the style will transition to a AnimationStatus.progress() of 0.0 over the provided LifeTime.
      transitionLifeTime - The LifeTime of the transition animation. It defines for ow long the AnimationStatus.progress() will transition from 0 to 1 or vice versa.
      styler - An AnimatedStyler lambda can define a set of style rules for the component wrapped by this builder by receiving an AnimationStatus and a ComponentStyleDelegate and returning an updated version with the desired style rules applied. The AnimatedStyler may apply the style properties according to the AnimationStatus and its AnimationStatus.progress() method (or other methods) to create a smooth transition between the 2 states.
      Returns:
      This builder instance, which enables fluent method chaining.
      See Also:

    • withTransitoryStyle

      public final I withTransitoryStyle(sprouts.Event styleEvent, LifeTime styleLifeTime, AnimatedStyler<C> styler)
      Allows you to configure a style which will be applied to the component temporarily when the provided Event is fired. The style will be applied for the provided LifeTime and then removed again. Here an example demonstrating how an event based style animation which temporarily defines a custom background and border color on a label: 
      
      UI.label("I have a highlight animation!")
      .withTransitoryStyle(vm.highlightEvent(), LifeTime.of(0.5, TimeUnit.SECONDS), (state, it) -> it
          .backgroundColor(new Color(0, 0, 0, (int)(state.progress() * 255)))
          .borderColor(new Color(255, 255, 255, (int)(state.progress() * 255)))
      )
      Parameters:
      styleEvent - The Event which should trigger the style animation.
      styleLifeTime - The LifeTime of the style animation.
      styler - An AnimatedStyler lambda can define a set of style rules for the component wrapped by this builder by receiving an AnimationStatus and a ComponentStyleDelegate and returning an updated version with the desired style rules applied. The AnimatedStyler may apply the style properties according to the AnimationStatus and its AnimationStatus.progress() method (or other methods) to create a smooth transition between the 2 states.
      Returns:
      This builder instance, which enables fluent method chaining.
      See Also:

    • withForeground

      public final I withForeground(Color color)
      Set the color of this JComponent. (This is usually the font color for components displaying text)
      This is in essence a convenience method, which avoid having to expose the underlying component through the UIForAnything.peek(Peeker) method like so: 
      
      UI.label("Something")
      .peek( label -> label.setForeground(Color.GRAY) );
      Parameters:
      color - The color of the foreground (usually text).
      Returns:
      This very builder to allow for method chaining.

    • withForegroundColor

      public final I withForegroundColor(String color)
      Allows you to define the Component.getForeground() color of the underlying JComponent using a color string. The supplied String is parsed to a UI.Color through the UIFactoryMethods.color(String) method for you.
      This is in essence a convenience method, which avoid having to expose the underlying component through the UIForAnything.peek(Peeker) method like so: 
      
      UI.label("Something")
      .peek( label -> label.setForeground(UI.color("oak")) );
      Parameters:
      color - A color string which should be parsed to a UI.Color instance and then set as the foreground color of the UI component.
      Returns:
      A new reference to this type of builder, to allow for fluent method chaining.

    • withForeground

      public final I withForeground(sprouts.Val<Color> fg)
      Use this to bind to a Val containing a foreground color. This is a convenience method, which works similar to: 
      
      UI.button("Click Me")
      .peek( button -> {
          fg.onChange(From.VIEW_MODEL,  v -> button.setForeground(v.get()) );
          button.setForeground(fg.get());
      });

      Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      fg - The foreground color which should be set for the UI component wrapped by a Val.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withForegroundIf

      public final I withForegroundIf(sprouts.Val<Boolean> condition, Color fg)
      Use this to bind to a foreground color which will be set dynamically based on a boolean property. Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      condition - The condition property which determines whether the foreground color should be set or not.
      fg - The foreground color which should be set for the UI component.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withForegroundIf

      public final I withForegroundIf(sprouts.Val<Boolean> condition, sprouts.Val<Color> color)
      Use this to dynamically bind to a foreground color which will be set dynamically based on a boolean property. Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      condition - The condition property which determines whether the foreground color should be set or not.
      color - The foreground color property which should be set for the UI component.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withForegroundIf

      public final I withForegroundIf(sprouts.Val<Boolean> condition, Color colorIfTrue, Color colorIfFalse)
      Use this to dynamically bind to a foreground color which will be set dynamically based on a boolean property. Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      condition - The condition property which determines whether the foreground color should be set or not.
      colorIfTrue - The foreground color which should be set for the UI component.
      colorIfFalse - The foreground color which should be set for the UI component.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withForegroundIf

      public final I withForegroundIf(sprouts.Val<Boolean> condition, sprouts.Val<Color> colorIfTrue, sprouts.Val<Color> colorIfFalse)
      Use this to dynamically bind to a foreground color which will be set dynamically based on a boolean property. Hint: Use myProperty.fire(From.VIEW_MODEL) in your view model to send the property value to this view component.
      Parameters:
      condition - The condition property which determines whether the foreground color should be set or not.
      colorIfTrue - The foreground color property which should be set for the UI component.
      colorIfFalse - The foreground color property which should be set for the UI component.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withMinSize

      @Deprecated public final I withMinSize(Dimension size)
      Deprecated.
      Due to the inherent pitfalls that come along with the Dimension being mutable!
      Use withMinSize(Size) instead.
      Set the minimum Dimension of this JComponent.
      This calls JComponent.setMinimumSize(Dimension) on the underlying component.
      Parameters:
      size - The minimum Dimension of the component.
      Returns:
      This very builder to allow for method chaining.

    • withMinSize

      public final I withMinSize(Size size)
      Set the minimum Size of this JComponent.
      This calls JComponent.setMinimumSize(Dimension) on the underlying component.
      Parameters:
      size - The minimum Size of the component.
      Returns:
      This very builder to allow for method chaining.

    • withMinSize

      public final I withMinSize(sprouts.Val<Size> size)
      Bind to a Val object to dynamically set the maximum Size of this JComponent.
      This calls JComponent.setMinimumSize(Dimension) (Dimension)} on the underlying component.
      This is a convenience method, which would be equivalent to: 
      
    UI.button("Click Me")
    .peek( button -> {
      size.onSetItem(JButton::setMinimumSize);
      button.setMinimumSize(size.get());
    });
      Parameters:
      size - The minimum Size of the component wrapped by a Val.
      Returns:
      This very builder to allow for method chaining.

    • withMinSize

      public final I withMinSize(int width, int height)
      Set the minimum width and heigh (Dimension) of this JComponent.
      This calls JComponent.setMinimumSize(Dimension) on the underlying component.
      Parameters:
      width - The minimum width of the component.
      height - The minimum height of the component.
      Returns:
      This very builder to allow for method chaining.

    • withMinSize

      public final I withMinSize(sprouts.Val<Integer> width, sprouts.Val<Integer> height)
      Bind to a Val object to dynamically set the minimum Dimension of this JComponent.
      This calls JComponent.setMinimumSize(Dimension) on the underlying component.
      Parameters:
      width - The minimum width of the component.
      height - The minimum height of the component.
      Returns:
      This very builder to allow for method chaining.

    • withMinWidth

      public final I withMinWidth(int width)
      Use this to only set the minimum width of this JComponent.
      This calls JComponent.setMinimumSize(Dimension) on the underlying component for you.
      Parameters:
      width - The minimum width which should be set for the underlying component.
      Returns:
      This very builder to allow for method chaining.

    • _setMinWidth

      protected final void _setMinWidth(C component, int width)

    • withMinWidth

      public final I withMinWidth(sprouts.Val<Integer> width)
      Use this to dynamically set only the minimum width of this JComponent.
      This calls JComponent.setMinimumSize(Dimension) on the underlying component for you.
      Parameters:
      width - The minimum width which should be set for the underlying component wrapped by a Val.
      Returns:
      This very builder to allow for method chaining.

    • withMinHeight

      public final I withMinHeight(int height)
      Use this to only set the minimum height of this JComponent.
      This calls JComponent.setMinimumSize(Dimension) on the underlying component for you.
      Parameters:
      height - The minimum height which should be set for the underlying component.
      Returns:
      This very builder to allow for method chaining.

    • _setMinHeight

      protected final void _setMinHeight(C component, int height)

    • withMinHeight

      public final I withMinHeight(sprouts.Val<Integer> height)
      Use this to dynamically set only the minimum height of this JComponent.
      This calls JComponent.setMinimumSize(Dimension) on the underlying component for you.
      Parameters:
      height - The minimum height which should be set for the underlying component wrapped by a Val.
      Returns:
      This very builder to allow for method chaining.

    • withMaxSize

      @Deprecated public final I withMaxSize(Dimension size)
      Deprecated.
      Due to the inherent pitfalls that come along with the Dimension being mutable!
      Use withMaxSize(Size) instead.
      Set the maximum Dimension of this JComponent.
      This calls JComponent.setMaximumSize(Dimension) on the underlying component.
      Parameters:
      size - The maximum Dimension of the component.
      Returns:
      This very builder to allow for method chaining.

    • withMaxSize

      public final I withMaxSize(Size size)
      Set the maximum Size of this JComponent.
      This calls JComponent.setMaximumSize(Dimension) on the underlying component.
      Parameters:
      size - The maximum Size of the component.
      Returns:
      This very builder to allow for method chaining.

    • withMaxSize

      public final I withMaxSize(sprouts.Val<Size> size)
      Bind to a Val object to dynamically set the maximum Size of this JComponent.
      This calls JComponent.setMaximumSize(Dimension) on the underlying component.
      Parameters:
      size - The maximum Size of the component wrapped by a Val.
      Returns:
      This very builder to allow for method chaining.

    • withMaxSize

      public final I withMaxSize(int width, int height)
      Set the maximum width and height (Dimension) of this JComponent.
      This calls JComponent.setMaximumSize(Dimension) on the underlying component.
      Parameters:
      width - The maximum width of the component.
      height - The maximum height of the component.
      Returns:
      This very builder to allow for method chaining.

    • withMaxSize

      public final I withMaxSize(sprouts.Val<Integer> width, sprouts.Val<Integer> height)
      Bind to a Val object to dynamically set the maximum size of this JComponent.
      This calls JComponent.setMaximumSize(Dimension) on the underlying component.
      Parameters:
      width - The maximum width of the component.
      height - The maximum height of the component.
      Returns:
      This very builder to allow for method chaining.

    • withMaxWidth

      public final I withMaxWidth(int width)
      Use this to only set the maximum width of this JComponent.
      This calls JComponent.setMaximumSize(Dimension) on the underlying component for you.
      Parameters:
      width - The maximum width which should be set for the underlying component.
      Returns:
      This very builder to allow for method chaining.

    • withMaxWidth

      public final I withMaxWidth(sprouts.Val<Integer> width)
      Use this to dynamically set only the maximum width of this JComponent.
      This calls JComponent.setMaximumSize(Dimension) on the underlying component for you.
      Parameters:
      width - The maximum width which should be set for the underlying component wrapped by a Val.
      Returns:
      This very builder to allow for method chaining.

    • withMaxHeight

      public final I withMaxHeight(int height)
      Use this to only set the maximum height of this JComponent.
      This calls JComponent.setMaximumSize(Dimension) on the underlying component for you.
      Parameters:
      height - The maximum height which should be set for the underlying component.
      Returns:
      This very builder to allow for method chaining.

    • withMaxHeight

      public final I withMaxHeight(sprouts.Val<Integer> height)
      Use this to dynamically set only the maximum height of this JComponent.
      This calls JComponent.setMaximumSize(Dimension) on the underlying component for you.
      Parameters:
      height - The maximum height which should be set for the underlying component wrapped by a Val.
      Returns:
      This very builder to allow for method chaining.

    • withPrefSize

      @Deprecated public final I withPrefSize(Dimension size)
      Deprecated.
      Due to the inherent pitfalls that come along with the Dimension being mutable!
      Please use withPrefSize(Size) instead.
      Set the preferred Dimension of this JComponent, which consists of a width and a height used as a suggestion to the LayoutManager of the parent container.
      This calls JComponent.setPreferredSize(Dimension) on the underlying component.
      Parameters:
      size - The preferred Dimension of the component.
      Returns:
      This very builder to allow for method chaining.

    • withPrefSize

      public final I withPrefSize(Size size)
      Set the preferred Size of this JComponent, which consists of a width and a height used as a suggestion to the LayoutManager of the parent container.
      This calls JComponent.setPreferredSize(Dimension) on the underlying component.
      Parameters:
      size - The preferred Size of the component.
      Returns:
      This very builder to allow for method chaining.

    • withPrefSize

      public final I withPrefSize(sprouts.Val<Size> size)
      Bind to a Val object to dynamically set the preferred Size of this JComponent, which consists of a width and a height used as a suggestion to the LayoutManager of the parent container.
      This calls JComponent.setPreferredSize(Dimension) on the underlying component.
      Parameters:
      size - A property holding the preferred Size of the component.
      Returns:
      This very builder to allow for method chaining.

    • withPrefSize

      public final I withPrefSize(int width, int height)
      Set the preferred width and height (Dimension) of this JComponent, which consists of a width and a height used as a suggestion to the LayoutManager of the parent container.
      This calls JComponent.setPreferredSize(Dimension) on the underlying component.
      Parameters:
      width - The preferred width of the component.
      height - The preferred height of the component.
      Returns:
      This very builder to allow for method chaining.

    • withPrefSize

      public final I withPrefSize(sprouts.Val<Integer> width, sprouts.Val<Integer> height)
      Bind to a Val object to dynamically set the preferred Dimension of this JComponent, which consists of a width and a height used as a suggestion to the LayoutManager of the parent container.
      This calls JComponent.setPreferredSize(Dimension) on the underlying component.
      Parameters:
      width - The preferred width of the component.
      height - The preferred height of the component.
      Returns:
      This very builder to allow for method chaining.

    • withPrefWidth

      public final I withPrefWidth(int width)
      Use this to only set the preferred width of this JComponent, which serves as a suggestion to the LayoutManager of the parent container.
      This calls JComponent.setPreferredSize(Dimension) on the underlying component for you.
      Parameters:
      width - The preferred width which should be set for the underlying component.
      Returns:
      This very builder to allow for method chaining.

    • _setPrefWidth

      protected final void _setPrefWidth(C component, int width)

    • withPrefWidth

      public final I withPrefWidth(sprouts.Val<Integer> width)
      Use this to dynamically set only the preferred width of this JComponent, which serves as a suggestion to the LayoutManager of the parent container.
      This calls JComponent.setPreferredSize(Dimension) on the underlying component for you.
      Parameters:
      width - The preferred width which should be set for the underlying component wrapped by a Val.
      Returns:
      This very builder to allow for method chaining.

    • withPrefHeight

      public final I withPrefHeight(int height)
      Use this to only set the preferred height of this JComponent, which serves as a suggestion to the LayoutManager of the parent container.
      This calls JComponent.setPreferredSize(Dimension) on the underlying component for you.
      Parameters:
      height - The preferred height which should be set for the underlying component.
      Returns:
      This very builder to allow for method chaining.

    • withPrefHeight

      public final I withPrefHeight(sprouts.Val<Integer> height)
      Use this to dynamically set only the preferred height of this JComponent, which serves as a suggestion to the LayoutManager of the parent container.
      This calls JComponent.setPreferredSize(Dimension) on the underlying component for you.
      Parameters:
      height - The preferred height which should be set for the underlying component wrapped by a Val.
      Returns:
      This very builder to allow for method chaining.

    • withSize

      @Deprecated public final I withSize(Dimension size)
      Deprecated.
      Due to the inherent pitfalls that come along with the Dimension being mutable!
      Please use withSize(Size) instead.
      Set the current Dimension)/size (width and height) of this JComponent.
      This calls Component.setSize(Dimension) on the underlying component.
      Parameters:
      size - The current Dimension of the component.
      Returns:
      This very builder to allow for method chaining.

    • withSize

      public final I withSize(Size size)
      Sets the current Size) (width and height) of this JComponent.
      Note however that calling this method, may not necessarily have a visual effect on the component, as the layout manager may override the size of the component.
      So in case of the component being part of a layout (which is the case most of the time), you may want to use the withPrefSize(Size) method instead.
      This calls Component.setSize(Dimension) on the underlying component.
      Parameters:
      size - The current Size of the component.
      Returns:
      This very builder to allow for method chaining.

    • withSize

      public final I withSize(sprouts.Val<Size> size)
      Bind to a Val object to dynamically set the current Dimension of this JComponent using a Size object.
      Note however that calling this method, may not necessarily have a visual effect on the component, as the layout manager may override the size of the component.
      So in case of the component being part of a layout (which is the case most of the time), you may want to use the withPrefSize(Val) method instead.
      The Size is automatically translated to a call to Component.setSize(Dimension) on the underlying component.
      Parameters:
      size - The current Size of the component wrapped by a Val property.
      Returns:
      This very builder to allow for method chaining.

    • withSize

      public final I withSize(int width, int height)
      Allows you to directly set the width and height of the current component directly instead of through the layout manager.
      Note however that calling this method, may not necessarily have a visual effect on the component, as the layout manager may override the size of the component.
      So in case of the component being part of a layout (which is the case most of the time), you may want to use the withPrefSize(int, int) method instead.
      Also note that this method translates to invoking Component.setSize(Dimension) on the underlying component.
      Parameters:
      width - The width of the component.
      height - The height of the component.
      Returns:
      This very builder to allow for method chaining.

    • withWidth

      public final I withWidth(int width)
      Set the current width of this JComponent.
      Note however that calling this method, may not necessarily have a visual effect on the component, as the layout manager may override the set width of the component.
      So in case of the component being part of a layout (which is the case most of the time), you may want to use the withPrefWidth(int) method instead.
      This calls Component.setSize(Dimension) on the underlying component.
      Parameters:
      width - The current width of the component.
      Returns:
      This very builder to allow for method chaining.

    • withWidth

      public final I withWidth(sprouts.Val<Integer> width)
      Bind to a Val object to dynamically set the current width of this JComponent.
      Note however that calling this method, may not necessarily have a visual effect on the component, as the layout manager may override the width of the component.
      So in case of the component being part of a layout (which is the case most of the time), you may want to use the withPrefWidth(Val) method instead.
      This calls Component.setSize(Dimension) on the underlying component.
      Parameters:
      width - The current width of the component wrapped by a Val.
      Returns:
      This very builder to allow for method chaining.

    • withHeight

      public final I withHeight(int height)
      Set the current height of this JComponent.
      Note however that calling this method, may not necessarily have a visual effect on the component, as the layout manager may override the height of the component.
      So in case of the component being part of a layout (which is the case most of the time), you may want to use the withPrefHeight(int) method instead.
      This calls Component.setSize(Dimension) on the underlying component.
      Parameters:
      height - The current height of the component.
      Returns:
      This very builder to allow for method chaining.

    • withHeight

      public final I withHeight(sprouts.Val<Integer> height)
      Bind to a Val object to dynamically set the current height of this JComponent.
      Note however that calling this method, may not necessarily have a visual effect on the component, as the layout manager may override the height of the component.
      So in case of the component being part of a layout (which is the case most of the time), you may want to use the withPrefHeight(Val) method instead.
      This calls Component.setSize(Dimension) on the underlying component.
      Parameters:
      height - The current height of the component wrapped by a Val.
      Returns:
      This very builder to allow for method chaining.

    • withSizeExactly

      public final I withSizeExactly(int width, int height)
      Allows you to define a common width and height for the minimum, maximum, and preferred size of this component. This is a convenience method, which is equivalent to: 
      
      .withMinSize(width, height)
      .withMaxSize(width, height)
      .withPrefSize(width, height)
      This method call translates to calling JComponent.setMinimumSize(Dimension), JComponent.setMaximumSize(Dimension), and JComponent.setPreferredSize(Dimension) on the underlying component.
      Parameters:
      width - The min-, max- and preferred with of the component.
      height - The min-, max- and preferred height of the component.
      Returns:
      A declarative builder instance to allow for further method chaining.

    • withSizeExactly

      public final I withSizeExactly(Size size)
      Allows you to define a common width and height for the minimum, maximum, and preferred size of this component in the form of the supplied Size object. This is in essence a convenience method equivalent to: 
      
      .withMinSize(size)
      .withMaxSize(size)
      .withPrefSize(size)
      Underneath, this method call translates to calling JComponent.setMinimumSize(Dimension), JComponent.setMaximumSize(Dimension), and JComponent.setPreferredSize(Dimension) on the underlying component.
      Parameters:
      size - The min-, max- and preferred Size of the component.
      Returns:
      A declarative builder instance to allow for further method chaining.

    • withSizeExactly

      public final I withSizeExactly(sprouts.Val<Size> size)
      Bind to a Size object to dynamically update the common width and height for the minimum, maximum, and preferred size of this component. This is in essence a convenience method, which is equivalent to calling: 
      
      .withMinSize(width, height)
      .withMaxSize(width, height)
      .withPrefSize(width, height)
      This method translates to calling JComponent.setMinimumSize(Dimension), JComponent.setMaximumSize(Dimension), and JComponent.setPreferredSize(Dimension) on the underlying component.
      Parameters:
      size - A property wrapping the min-, max- and preferred Size of the component. When the property item changes, the size of the component will be updated accordingly.
      Returns:
      A declarative builder instance to allow for further method chaining.

    • withSizeExactly

      public final I withSizeExactly(sprouts.Val<Integer> width, sprouts.Val<Integer> height)
      Allows you to bind to two Val properties to dynamically update the common width and height for the minimum, maximum, and preferred size of this component. This is in essence a convenience method, which is equivalent to: 
      
      .withMinSize(width, height)
      .withMaxSize(width, height)
      .withPrefSize(width, height)
      This method will translate the property updates to calling JComponent.setMinimumSize(Dimension), JComponent.setMaximumSize(Dimension), and JComponent.setPreferredSize(Dimension) on the underlying component.
      Parameters:
      width - The min-, max- and preferred width of the component in the form of an integer property. When the property item changes, the width of the component will be updated accordingly.
      height - The min-, max- and preferred height of the component in the form of an integer property. When the property item changes, the height of the component will be updated accordingly.
      Returns:
      A declarative builder instance to allow for further method chaining.
      Throws:
      NullPointerException - If any of the provided properties is null.

    • withWidthExactly

      public final I withWidthExactly(int width)
      Use this to set the min-, max- and preferred width of this JComponent to the same value.
      This is a convenience method, which is equivalent to calling: 
      
      .withMinWidth(width)
      .withMaxWidth(width)
      .withPrefWidth(width)
      An invocation to this method translates to JComponent.setMinimumSize(Dimension), JComponent.setMaximumSize(Dimension), and JComponent.setPreferredSize(Dimension) on the underlying component.
      Parameters:
      width - The min-, max- and preferred width of the component.
      Returns:
      A declarative builder instance to allow for further method chaining.

    • withWidthExactly

      public final I withWidthExactly(sprouts.Val<Integer> width)
      Use this to bind to a Val property to dynamically update the min-, max- and preferred width of this JComponent to the same value.
      So whenever the item of the property changes, all these widths will be updated automatically for you. This is a convenience method, which is equivalent to calling withMinWidth(Val), withMaxWidth(Val) and withPrefWidth(Val) on the underlying component. 
      
      .withMinWidth(width)
      .withMaxWidth(width)
      .withPrefWidth(width)
      Eventually, all of this ultimately translates to JComponent.setMinimumSize(Dimension), JComponent.setMaximumSize(Dimension), and JComponent.setPreferredSize(Dimension) on the underlying component.
      Parameters:
      width - The min-, max- and preferred width of the component wrapped by a Val. When the property item changes, the width of the component will be updated accordingly.
      Returns:
      A declarative builder instance to allow for further method chaining.

    • withHeightExactly

      public final I withHeightExactly(int height)
      Use this to set the min-, max- and preferred height of this JComponent to the same value.
      This is a convenience method, which is equivalent to calling: 
      
      .withMinHeight(height)
      .withMaxHeight(height)
      .withPrefHeight(height)
      An invocation to this method translates to JComponent.setMinimumSize(Dimension), JComponent.setMaximumSize(Dimension), and JComponent.setPreferredSize(Dimension) on the underlying component.
      Parameters:
      height - The min-, max- and preferred height of the component.
      Returns:
      A declarative builder instance to allow for further method chaining.

    • withHeightExactly

      public final I withHeightExactly(sprouts.Val<Integer> height)
      Use this to bind to a Val property to dynamically update the min-, max- and preferred height of this JComponent to the same value.
      So whenever the item of the property changes, all these heights will be updated automatically for you. This is a convenience method, which is equivalent to calling withMinHeight(Val), withMaxHeight(Val) and withPrefHeight(Val) on the underlying component. 
      
      .withMinHeight(height)
      .withMaxHeight(height)
      .withPrefHeight(height)
      Eventually, all of this ultimately translates to JComponent.setMinimumSize(Dimension), JComponent.setMaximumSize(Dimension), and JComponent.setPreferredSize(Dimension) on the underlying component.
      Parameters:
      height - The min-, max- and preferred height of the component wrapped by a Val. When the property item changes, the height of the component will be updated accordingly.
      Returns:
      A declarative builder instance to allow for further method chaining.

    • onMouseClick

      public final I onMouseClick(sprouts.Action<ComponentMouseEventDelegate<C>> onClick)
      Calls the provided action event handler when the mouse gets pressed and then released. This delegates to a MouseListener based mouse click event listener registered in the UI component.

      Note that a click is defined as the combination of the mouse being pressed and then released on the same position as it was pressed. If the mouse moves between the press and the release events, then the event is considered a drag event instead of a mouse click! (see onMouseDrag(Action))
      Parameters:
      onClick - The lambda instance which will be passed to the button component as MouseListener.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onMouseRelease

      public final I onMouseRelease(sprouts.Action<ComponentMouseEventDelegate<C>> onRelease)
      Use this to register and catch generic MouseListener based mouse release events on this UI component. This method adds the provided consumer lambda to an anMouseListener instance to the component.

      Parameters:
      onRelease - The lambda instance which will be passed to the button component as MouseListener.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onMousePress

      public final I onMousePress(sprouts.Action<ComponentMouseEventDelegate<C>> onPress)
      Use this to register and catch generic MouseListener based mouse press events on this UI component. This method adds the provided consumer lambda to an anMouseListener instance to the component.

      Parameters:
      onPress - The lambda instance which will be passed to the button component as MouseListener.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onMouseEnter

      public final I onMouseEnter(sprouts.Action<ComponentMouseEventDelegate<C>> onEnter)
      Use this to register and catch mouse enter events on the UI.ComponentArea.BODY of this UI component,
      which consists of the full component boundaries except for the surrounding margins and corner rounding areas.

      If you want to catch mouse enter events on a different area of the component, use onMouseEnter(UI.ComponentArea, Action) instead. Internally, this method adds the supplied Action lambda to a custom event dispatcher which ensures that the mouse enter event is only triggered when the mouse enters the boundaries of the specified area, irrespective of the existence of child components.

      Parameters:
      onEnter - The lambda instance which will be passed to the button component as MouseListener.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onMouseEnter

      public final I onMouseEnter(UI.ComponentArea area, sprouts.Action<ComponentMouseEventDelegate<C>> onEnter)
      Use this to register and catch mouse enter events on a specific area of this UI component, defined by the first argument, a UI.ComponentArea enum value, and the second argument, a lambda instance which will be invoked when the mouse enters the specified area. Internally, the provided Action lambda is handled by a custom event dispatcher which ensures that the mouse enter event is only triggered when the mouse enters the boundaries of the specified area, irrespective of the existence of child components.

      Note that this mouse enter event is different from the native Swing mouse enter event, which also considers child components with mouse listeners as enter/exit boundaries.
      If you want to rely on this the Swing behavior, use onMouseEnterGreedy(Action) instead.
      We do however recommended to rely on this method, to avoid bugs due to the unexpected side effect of enter events being fired at the boundary to child components.
      Parameters:
      area - The specific area of the component where the mouse enter event should be caught.
      onEnter - The lambda instance which will be passed to the button component as MouseListener.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onMouseEnterGreedy

      public final I onMouseEnterGreedy(sprouts.Action<ComponentMouseEventDelegate<C>> onEnter)
      Use this to register and catch simple MouseListener based mouse enter events on this UI component. This method adds the supplied Action lambda in a MouseListener instance to the component.

      This method is greedy in the sense that in case of the parent of this component also having a mouse listener, then a mouse cursor transition on top of this component will be considered an exit from the parent component and an enter into this component.
      If you want to catch mouse enter events strictly in terms of the cursor being inside the component boundaries, or one of its areas, use onMouseEnter(Action), or onMouseEnter(UI.ComponentArea, Action) instead.

      To avoid bugs due to the unexpected side effect of enter events being fired at the surface boundaries to child components, we recommend to use onMouseEnter(Action) instead of this method!
      Also note that this method is different from onMouseEnter(Action), in that it reports enter events at the boundaries of UI.ComponentArea.ALL instead of UI.ComponentArea.BODY.

      Parameters:
      onEnter - The lambda instance which will be passed to the button component as MouseListener.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onMouseExit

      public final I onMouseExit(sprouts.Action<ComponentMouseEventDelegate<C>> onExit)
      Use this to register and catch mouse exit events on the UI.ComponentArea.BODY of this UI component,
      which consists of the full component boundaries except for the surrounding margins and corner rounding areas.

      If you want to catch mouse exit events on a different area than the body of the component, use onMouseExit(UI.ComponentArea, Action) instead. Internally, this method adds the supplied Action lambda to a custom event dispatcher which ensures that the mouse exit event is only triggered when the mouse exits the boundaries of the specified area, irrespective of the existence of child components.

      Note that this mouse enter event is different from the native Swing mouse enter event, which also considers child components with mouse listeners as enter/exit event boundaries.
      If you want to rely on this the Swing behavior, use onMouseExitGreedy(Action) instead.
      We do however recommended to rely on this method, to avoid bugs due to the unexpected side effect of exit events being fired at the boundary to child components.

      Parameters:
      onExit - The lambda instance which will be passed to the button component as MouseListener.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onMouseExit

      public final I onMouseExit(UI.ComponentArea area, sprouts.Action<ComponentMouseEventDelegate<C>> onExit)
      Use this to register and catch mouse exit events on a specific area of this UI component, by supplying a UI.ComponentArea enum value to define the area, and a Action lambda which will be invoked when the mouse exits the specified area, so that you can react to the event accordingly.

      Internally, the provided Action lambda is handled by a custom event dispatcher which ensures that the mouse exit event is only triggered when the mouse exits the boundaries of the specified area, irrespective of the existence of child components.

      Note that this mouse exit event is different from the native Swing mouse exit event, which also considers child components with mouse listeners as enter/exit boundaries. If you want to rely on the native Swing behavior, use onMouseExitGreedy(Action) instead of this method.

      Parameters:
      area - The specific area of the component where the mouse exit event should be caught.
      onExit - The lambda instance which will be passed to the button component as MouseListener.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onMouseExitGreedy

      public final I onMouseExitGreedy(sprouts.Action<ComponentMouseEventDelegate<C>> onExit)
      Use this to register and catch simple MouseListener based mouse exit events on this UI component. This method adds the supplied Action lambda in a MouseListener instance to the component.

      The method is considered greedy in the sense that in case of the parent of this component also having a mouse listener, then a mouse cursor transition over to be on top of this component will be considered an exit from the parent components and an enter into this component.
      If you want to catch mouse exit events strictly in terms of the cursor being inside the component boundaries, or one of its areas, use onMouseExit(Action), or onMouseExit(UI.ComponentArea, Action) instead.

      To avoid bugs due to the unexpected side effect of exit events being fired at the surface boundaries to child components, we recommend to use onMouseExit(Action) instead of this method!
      Also note that this method is different from onMouseExit(Action), in that it reports exit events at the boundaries of UI.ComponentArea.ALL instead of UI.ComponentArea.BODY.

      Parameters:
      onExit - The lambda instance which will be passed to the button component as MouseListener.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onMouseDrag

      public final I onMouseDrag(sprouts.Action<ComponentDragEventDelegate<C>> onDrag)
      Use this to register and catch generic MouseListener based mouse drag events on this UI component. This method adds the provided consumer lambda to an anMouseListener instance to the component.

      The ComponentDragEventDelegate received by the Action lambda exposes both component and drag event context information, including a list of all the MouseEvents involved in one continuous dragging motion (see ComponentDragEventDelegate.dragEvents() for more information).
      Parameters:
      onDrag - The lambda instance which will be passed to the button component as MouseListener.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onMouseMove

      public final I onMouseMove(sprouts.Action<ComponentMouseEventDelegate<C>> onMove)
      Use this to register and catch generic MouseListener based mouse move events on this UI component. This method adds the provided consumer lambda to an anMouseListener instance to the component.

      Parameters:
      onMove - The lambda instance which will be passed to the button component as MouseListener.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onMouseWheelMove

      public final I onMouseWheelMove(sprouts.Action<ComponentDelegate<C,MouseWheelEvent>> onWheel)
      Use this to register and catch generic MouseListener based mouse wheel events on this UI component. This method adds the provided consumer lambda to an anMouseListener instance to the component.

      Parameters:
      onWheel - The lambda instance which will be passed to the button component as MouseListener.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onMouseWheelUp

      public final I onMouseWheelUp(sprouts.Action<ComponentDelegate<C,MouseWheelEvent>> onWheelUp)
      Use this to register and catch mouse wheel up movement events on this UI component. This method adds the provided consumer lambda to an anMouseListener instance to the component.

      Parameters:
      onWheelUp - The lambda instance which will be passed to the button component as MouseListener.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onMouseWheelDown

      public final I onMouseWheelDown(sprouts.Action<ComponentDelegate<C,MouseWheelEvent>> onWheelDown)
      Use this to register and catch mouse wheel down movement events on this UI component. This method adds the provided consumer lambda to an anMouseListener instance to the component.

      Parameters:
      onWheelDown - The lambda instance which will be passed to the button component as MouseListener.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onResize

      public final I onResize(sprouts.Action<ComponentDelegate<C,ComponentEvent>> onResize)
      The provided lambda will be invoked when the component's size changes. This will internally translate to a ComponentListener implementation. Passing null to this method will cause an exception to be thrown.
      Parameters:
      onResize - The resize action which will be called when the underlying component changes size.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onMoved

      public final I onMoved(sprouts.Action<ComponentDelegate<C,ComponentEvent>> onMoved)
      The provided lambda will be invoked when the component was moved. This will internally translate to a ComponentListener implementation.
      Parameters:
      onMoved - The action lambda which will be executed once the component was moved / its position canged.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onShown

      public final I onShown(sprouts.Action<ComponentDelegate<C,AncestorEvent>> onShown)
      Adds the supplied Action wrapped in a AncestorListener to the component, to receive calls when the wrapped component becomes visible on the screen.

      Note that this does not correlate 1:1 with the Component.isVisible() flag, because a component may also be invisible when it is not part of the component hierarchy with a visible root component (window) or one of its ancestors (parent components) is not visible.

      Parameters:
      onShown - The Action which gets invoked when the component has been made visible
      Returns:
      This very instance, which enables builder-style method chaining.

    • onHidden

      public final I onHidden(sprouts.Action<ComponentDelegate<C,AncestorEvent>> onHidden)
      Adds the supplied Action wrapped in a AncestorListener to the component, to receive calls when the wrapped component becomes invisible on the users screen.

      Note that this does not correlate 1:1 with the Component.isVisible() flag, because a component may also be invisible when it is not part of the component hierarchy with a visible root component (window) or one of its ancestors (parent components) is not visible.

      Parameters:
      onHidden - The Action which gets invoked when the component has been made invisible.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onFocusGain

      public final I onFocusGain(sprouts.Action<ComponentDelegate<C,ComponentEvent>> onFocus)
      Adds the supplied Action wrapped in a FocusListener to the component, to receive those focus events where the wrapped component gains input focus.
      Parameters:
      onFocus - The Action which should be executed once the input focus was gained on the wrapped component.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onFocusLoss

      public final I onFocusLoss(sprouts.Action<ComponentDelegate<C,ComponentEvent>> onFocus)
      Adds the supplied Action wrapped in a focus listener to receive those focus events where the wrapped component loses input focus.
      Parameters:
      onFocus - The Action which should be executed once the input focus was lost on the wrapped component.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onKeyPress

      public final I onKeyPress(sprouts.Action<ComponentDelegate<C,KeyEvent>> onKeyPressed)
      Adds the supplied Action wrapped in a KeyListener to the component, to receive key events triggered when the wrapped component receives keyboard input.

      Parameters:
      onKeyPressed - The Action which will be executed once the wrapped component received a key press.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onPressed

      public final I onPressed(Keyboard.Key key, sprouts.Action<ComponentDelegate<C,KeyEvent>> onKeyPressed)
      Adds the supplied Action wrapped in a KeyListener to the component, to receive key events triggered when the wrapped component receives a particular keyboard input matching the provided Keyboard.Key.

      Parameters:
      key - The Keyboard.Key which should be matched to the key event.
      onKeyPressed - The Action which will be executed once the wrapped component received the targeted key press.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onKeyRelease

      public final I onKeyRelease(sprouts.Action<ComponentDelegate<C,KeyEvent>> onKeyReleased)
      Adds the supplied Action wrapped in a KeyListener to the component, to receive key events triggered when the wrapped component receives keyboard input.

      Parameters:
      onKeyReleased - The Action which will be executed once the wrapped component received a key release.
      Returns:
      This very instance, which enables builder-style method chaining.
      See Also:

    • onRelease

      public final I onRelease(Keyboard.Key key, sprouts.Action<ComponentDelegate<C,KeyEvent>> onKeyReleased)
      Adds the supplied Action wrapped in a KeyListener to the component, to receive key events triggered when the built component receives a particular keyboard input matching the provided Keyboard.Key.

      Parameters:
      key - The Keyboard.Key which should be matched to the key event.
      onKeyReleased - The Action which will be executed once the wrapped component received the targeted key release.
      Returns:
      This very instance, which enables builder-style method chaining.
      See Also:

    • onKeyTyped

      public final I onKeyTyped(sprouts.Action<ComponentDelegate<C,KeyEvent>> onKeyTyped)
      Adds the supplied Action wrapped in a KeyListener to the component, to receive key events triggered when the wrapped component receives keyboard input.

      Parameters:
      onKeyTyped - The Action which will be executed once the wrapped component received a key typed.
      Returns:
      This very instance, which enables builder-style method chaining.
      See Also:

    • onTyped

      public final I onTyped(Keyboard.Key key, sprouts.Action<ComponentDelegate<C,KeyEvent>> onKeyTyped)
      Adds the supplied Action wrapped in a KeyListener to the component, to receive key events triggered when the wrapped component receives a particular keyboard input matching the provided Keyboard.Key.

      Parameters:
      key - The Keyboard.Key which should be matched to the key event.
      onKeyTyped - The Action which will be executed once the wrapped component received the targeted key typed.
      Returns:
      This very instance, which enables builder-style method chaining.
      See Also:

    • onTyped

      public final I onTyped(char character, sprouts.Action<ComponentDelegate<C,KeyEvent>> onKeyTyped)
      Adds the supplied Action wrapped in a KeyListener to the component, to receive key events triggered when the wrapped component receives a particular keyboard input matching the provided character.
      This method is a logical extension of the onTyped(Keyboard.Key, Action) method, with the difference that it listens for any character instead of a specific key code. This also works with special characters which are typed using the combination of multiple keys (e.g. shift + number keys).

      Parameters:
      character - The character to listen for.
      onKeyTyped - The action to execute when the character is typed.
      Returns:
      This very instance, which enables builder-style method chaining.
      See Also:

    • onCharTyped

      public final I onCharTyped(sprouts.Action<ComponentDelegate<C,KeyEvent>> onKeyTyped)
      Adds the supplied Action wrapped in a KeyListener to the component, to receive key events triggered when the wrapped component receives a particular keyboard input matching the provided character.
      This method is a logical extension of the onTyped(Keyboard.Key, Action) method, with the difference that it listens for any character instead of a specific key code. This also works with special characters which are typed using the combination of multiple keys (e.g. shift + number keys).

      Parameters:
      onKeyTyped - The action to execute when the character is typed.
      Returns:
      This very instance, which enables builder-style method chaining.
      See Also:

    • withDragAway

      public final I withDragAway(Configurator<DragAwayComponentConf<C>> configurator)
      Exposes a functional Configurator API for turning the component into a drag source site with the given configuration. This method is a convenience method which internally creates and configures an AWT native DragSource instance for the component.

      Here an example: 
      
      UI.label("Drag me!")
      .withDragAway( conf -> conf
          .enabled(true)
          .opacity(0.25)
          .payload("IT WORKS")
          .onDragMove( it -> {...})
      )
      The example above creates a draggable label which will be dragged with an opacity of 0.25 and carries the payload "IT WORKS" when dragged. The drag move event handler is attached to the drag source site and will be called when the label is dragged.

      If you want to create a drop site instead of a drag source site, use withDropSite(Configurator).

      Parameters:
      configurator - The Configurator which allows you to configure the drag source site by receiving a DragAwayComponentConf instance.
      Returns:
      This very instance, which enables builder-style method chaining.

    • withDropSite

      public final I withDropSite(Configurator<DragDropComponentConf<C>> configurator)
      Exposes a functional Configurator API for turning the component into a drag drop receiver site with the given configuration. This method is a convenience method which internally creates and configures an AWT native DropTarget instance for the component.

      Here an example: 
      
      UI.label("Drop here!")
      .withDropSite( conf -> conf
          .onDragOver( it -> {
              it.animateFor(1, TimeUnit.SECONDS, status -> {
                  double r = 30 * status.fadeIn() * it.getScale();
                  double x = it.getEvent().getLocation().x - r / 2.0;
                  double y = it.getEvent().getLocation().y - r / 2.0;
                  it.paint(status, g -> {
                      g.setColor(new Color(0f, 1f, 1f, (float) status.fadeOut()));
                      g.fillOval((int) x, (int) y, (int) r, (int) r);
                  });
              });
          })
          .onDrop(it -> {
              it.animateFor(2, TimeUnit.SECONDS, status -> {
                  double r = 480 * status.fadeIn() * it.getScale();
                  double x = it.getEvent().getLocation().x - r / 2.0;
                  double y = it.getEvent().getLocation().y - r / 2.0;
                  it.paint(status, g -> {
                      g.setColor(UI.color(0.5+status.fadeOut()/2, status.fadeOut(), status.fadeIn(), status.fadeOut()));
                      g.fillOval((int) x, (int) y, (int) r, (int) r);
                  });
              });
          })
      )
      The example above creates a drop site label which will animate an expanding circle when a drag is over it and another circle when a drop is performed on it. The drag over event handler is attached to the drop site and will be called when the label is dragged over it.

      If you want to create a drag source site instead of a drop site, use withDragAway(Configurator).

      Parameters:
      configurator - The Configurator which allows you to configure the drop site by receiving a DragDropComponentConf instance.
      Returns:
      This very instance, which enables builder-style method chaining.

    • onView

      public final <E extends sprouts.Observable> I onView(E observableEvent, sprouts.Action<ComponentDelegate<C,E>> action)
      Allows you to cause an effect inside your UI when an observable event is fired. The provided Action event handler will be called on the UI thread when the Observable event is fired, irrespective of what thread the Observable event is fired on. However, it is expected that the Observable event is fired on the application thread and the concrete implementation of the Observable is intended to be part of your view model.

      Here an example: 
      
  UI.label("I have a color animation!")
  .on(viewModel.someEvent(), it ->
    it.animateFor(3, TimeUnit.SECONDS, status -> {
      double r = status.progress();
      double g = 1 - status.progress();
      double b = status.pulse();
      it.setBackgroundColor(r, g, b);
    })
  )
      Type Parameters:
      E - The type of the Observable event.
      Parameters:
      observableEvent - The Observable event to which the Action should be attached and called on the UI thread when the event is fired in the view model.
      action - The Action which is invoked by the UI thread after the Observable event was fired by the business logic of the view model.
      Returns:
      This very instance, which enables builder-style method chaining.

    • on

      public final <E extends sprouts.Observable> I on(E observableEvent, sprouts.Action<ComponentDelegate<C,E>> action)
      Use this to attach a component Action event handler to a functionally supplied Observable event in order to implement a custom user event system. The supplied Action is executed on the application thread when the Observable event is fired and irrespective of the thread that Observable fired the event.
      The Action is expected to perform an effect on the view model or the application state, but not on the UI directly.
      (see onView(Observable, Action) if you want your view model to affect the UI through an observable event)

      Consider the following example: 
      
      UI.label("")
      .on(CustomEventSystem.touchGesture(), it -> ..some App update.. )
      In this example we use an imaginary CustomEventSystem to register a touch gesture event handler which will be called on the application thread when the touch gesture event is fired. Although neither Swing nor SwingTree have a touch gesture event system, this example illustrates how one could easily integrate a custom event system into SwingTree UIs.

      Note that the provided Observable event is NOT expected to be part of the view model, but rather part of a custom event system that captures user input or other input which is not directly related to the business logic of the view model.
      Type Parameters:
      E - The type of the Observable event.
      Parameters:
      observableEvent - The Observable event to which the Action should be attached.
      action - The Action which is invoked by the application thread after the Observable event was fired.
      Returns:
      This very instance, which enables builder-style method chaining.
      See Also:

    • on

      public final <E extends sprouts.Observable> I on(Function<C,E> eventSource, sprouts.Action<ComponentDelegate<C,E>> action)
      This is a logical extension of the on(Observable, Action) method. Use this to attach a component Action event handler to a functionally supplied Observable event. The Action will be called on the application thread when the Observable event is fired, irrespective of the thread that fired the Observable event. The Action is expected to perform an effect on the view model or the application state, but not on the UI directly.
      (see onView(Observable, Action) if you want your view model to affect the UI through an observable event)

      Consider the following example: 
      
      UI.label("")
      .on(c -> CustomEventSystem.touchGesture(c), it -> ..some App update.. )
      Which may also be written as: 
      
    UI.label("")
    .on(CustomEventSystem::touchGesture, it -> ..some App update.. )
      In this example we use an imaginary CustomEventSystem to register a component specific touch gesture event handler which will be called on the application thread when the touch gesture event is fired. Although neither Swing nor SwingTree have a touch gesture event system, this example illustrates how one could easily integrate a custom event system into SwingTree UIs.

      Note that the Observable event supplied by the function is NOT expected to be part of the view model, but rather be part of a custom event system that captures user input or other input which is not directly related to the business logic of the view model.
      Type Parameters:
      E - The type of the Observable event.
      Parameters:
      eventSource - The Observable event to which the Action should be attached.
      action - The Action which is invoked by the application thread after the Observable event was fired.
      Returns:
      This very instance, which enables builder-style method chaining.
      See Also:

    • doUpdates

      public final I doUpdates(int delay, sprouts.Action<ComponentDelegate<C,ActionEvent>> onUpdate)
      Use this to register periodic update actions which should be called based on the provided delay!
      The following example produces a label which will display the current date. 
      
      UI.label("")
      .doUpdates( 100, it -> it.getComponent().setText(new Date().toString()) )
      Parameters:
      delay - The delay in milliseconds between calling the provided Action.
      onUpdate - The Action which should be called periodically.
      Returns:
      This very instance, which enables builder-style method chaining.

    • _addComponentTo

      protected void _addComponentTo(C thisComponent, JComponent addedComponent, @Nullable AddConstraint constraints)
      Description copied from class: UIForAnything
      This builder class expects its implementations to be builder types for anything which can be built in a nested tree-like structure. Implementations of this abstract method ought to enable support for nested building.

      Specified by:
      _addComponentTo in class UIForAnything<I,C extends JComponent,JComponent>
      Parameters:
      thisComponent - The component which is wrapped by this builder.
      addedComponent - A component instance which ought to be added to the wrapped component type.
      constraints - The layout constraint which ought to be used to add the component to the wrapped component type.

    • add

      public final <T extends JComponent> I add(String attr, UIForAnySwing<?,T> builder)
      Use this to nest builder nodes into this builder to effectively plug the wrapped JComponents into the JComponent type wrapped by this builder instance. The first argument is expected to contain layout information for the layout manager of the wrapped JComponent, through the Container.add(Component, Object) method. By default, the MigLayout is used.

      Type Parameters:
      T - The type of the JComponent which is wrapped by the provided builder.
      Parameters:
      attr - The additional mig-layout information which should be passed to the UI tree.
      builder - A builder for another JComponent instance which ought to be added to the wrapped component type.
      Returns:
      This very instance, which enables builder-style method chaining.

    • add

      public final <T extends JComponent> I add(AddConstraint attr, UIForAnySwing<?,T> builder)
      Use this to nest builder nodes into this builder to effectively plug the wrapped JComponents into the JComponent type wrapped by this builder instance. The first argument will be passed to the layout manager of the wrapped JComponent, through the Container.add(Component, Object) method. By default, the MigLayout is used.

      Type Parameters:
      T - The type of the JComponent which is wrapped by the provided builder.
      Parameters:
      attr - The mig-layout attribute.
      builder - A builder for another JComponent instance which ought to be added to the wrapped component type.
      Returns:
      This very instance, which enables builder-style method chaining.

    • add

      @SafeVarargs public final <B extends UIForAnySwing<?, ?>> I add(String attr, B... builders)
      Use this to nest builder types into this builder to effectively plug the wrapped JComponents into the JComponent type wrapped by this builder instance. The first argument represents layout attributes/constraints which will be passed to the LayoutManager of the underlying JComponent. through the Container.add(Component, Object) method.

      This may look like this: 
      
    UI.panel()
    .add("wrap", UI.label("A"), UI.label("B"))
    .add("grow", UI.label("C"), UI.label("D"))
      Note that the first argument, "wrap" and "grow" in this case, are used as layout constraints for all the JComponents which are added in the subsequent arguments of a single call to this method.
      Type Parameters:
      B - The builder type parameter, a subtype of UIForAnySwing.
      Parameters:
      attr - The additional mig-layout information which should be passed to the UI tree.
      builders - An array of builders for a corresponding number of JComponent type which ought to be added to the wrapped component type of this builder.
      Returns:
      This very instance, which enables builder-style method chaining.

    • add

      @SafeVarargs public final <B extends UIForAnySwing<?, ?>> I add(AddConstraint attr, B... builders)
      Use this to nest builder types into this builder to effectively plug the wrapped JComponents into the JComponent type wrapped by this builder instance. The first argument will be passed to the LayoutManager of the underlying JComponent to serve as layout constraints through the Container.add(Component, Object) method.

      Type Parameters:
      B - The builder type parameter, a subtype of UIForAnySwing.
      Parameters:
      attr - The first mig-layout information which should be passed to the UI tree.
      builders - An array of builders for a corresponding number of JComponent type which ought to be added to the wrapped component type of this builder.
      Returns:
      This very instance, which enables builder-style method chaining.

    • add

      @SafeVarargs public final <B extends UIForAnySwing<?, ?>> I add(net.miginfocom.layout.CC attr, B... builders)
      Use this to nest builder types into this builder to effectively plug the JComponents wrapped by the provided builders into the JComponent type wrapped by this builder instance. The first argument represents placement constraints for the provided components which will be passed to the MigLayout of the underlying JComponent through the Container.add(Component, Object) method.

      Type Parameters:
      B - The builder type parameter, a subtype of UIForAnySwing.
      Parameters:
      attr - The additional mig-layout information which should be passed to the UI tree.
      builders - An array of builders for a corresponding number of JComponent type which ought to be added to the wrapped component type of this builder.
      Returns:
      This very instance, which enables builder-style method chaining.

    • add

      @SafeVarargs public final <E extends JComponent> I add(String attr, E... components)
      Use this to nest JComponent types into this builder to effectively plug the provided JComponents into the JComponent type wrapped by this builder instance. The first argument represents layout attributes/constraints which will be applied to the subsequently provided JComponent types.

      This may look like this: 
      
    UI.panel()
    .add("wrap", new JLabel("A"), new JLabel("B"))
    .add("grow", new JLabel("C"), new JLabel("D"))
      Note that the first argument, "wrap" and "grow" in this case, are used as layout constraints for all the JComponents which are added in the subsequent arguments of a single call to this method.
      Type Parameters:
      E - The type of the JComponent which is wrapped by the provided builder.
      Parameters:
      attr - The additional layout information which should be passed to the UI tree.
      components - A JComponents array which ought to be added to the wrapped component type.
      Returns:
      This very instance, which enables builder-style method chaining.

    • add

      @SafeVarargs public final <E extends JComponent> I add(AddConstraint attr, E... components)
      Use this to nest JComponent types into this builder to effectively plug the provided JComponents into the JComponent type wrapped by this builder instance. The first 2 arguments will be joined by a comma and passed to the LayoutManager of the underlying JComponent to serve as layout constraints.

      Type Parameters:
      E - The type of the JComponent which is wrapped by the provided builder.
      Parameters:
      attr - The first layout information which should be passed to the UI tree.
      components - A JComponents array which ought to be added to the wrapped component type.
      Returns:
      This very instance, which enables builder-style method chaining.

    • add

      public final <M> I add(sprouts.Val<M> model, ViewSupplier<M> viewSupplier)
      This allows you to dynamically generate a view for the item of a property (usually a property holding a sub-view model) and automatically regenerate the view when the property changes. The ViewSupplier lambda passed to this method will receive the value of the property and is then expected to return a JComponent instance which will be added to the wrapped JComponent type of this builder.
      Type Parameters:
      M - The type of the value held by the Val property.
      Parameters:
      model - A Val property holding null or any other type of value, preferably a view model instance.
      viewSupplier - A ViewSupplier instance which will be used to generate the view for the value held by the property.
      Returns:
      This very instance, which enables builder-style method chaining.

    • add

      public final <M> I add(String attr, sprouts.Val<M> model, ViewSupplier<M> viewSupplier)
      This allows you to dynamically generate a view for the item of a property (usually a property holding a sub-view model) and automatically regenerate the view when the property changes. The ViewSupplier lambda passed to this method will receive the value of the property and is then expected to return a JComponent instance which will be added to the wrapped JComponent type of this builder.
      Type Parameters:
      M - The type of the value held by the Val property.
      Parameters:
      attr - The layout information which should be used as layout constraints for the generated view.
      model - A Val property holding null or any other type of value, preferably a view model instance.
      viewSupplier - A ViewSupplier instance which will be used to generate the view for the value held by the property.
      Returns:
      This very instance, which enables builder-style method chaining.

    • add

      public final <M> I add(AddConstraint attr, sprouts.Val<M> model, ViewSupplier<M> viewSupplier)
      This allows you to dynamically generate a view for the item of a property (usually a property holding a sub-view model) and automatically regenerate the view when the property changes. The ViewSupplier lambda passed to this method will receive the value of the property and is then expected to return a JComponent instance which will be added to the wrapped JComponent type of this builder.
      Type Parameters:
      M - The type of the value held by the Val property.
      Parameters:
      attr - The layout information which should be used as layout constraints for the generated view.
      model - A Val property holding null or any other type of value, preferably a view model instance.
      viewSupplier - A ViewSupplier instance which will be used to generate the view for the value held by the property.
      Returns:
      This very instance, which enables builder-style method chaining.

    • addAll

      public final <M> I addAll(sprouts.Vals<M> models, ViewSupplier<M> viewSupplier)
      This allows you to dynamically generate views for the items in a Vals property list and automatically regenerate the view when any of the items change. The type of item can be anything, but it is usually a view model instance. The ViewSupplier lambda passed to this method will receive the value of the property and is then expected to return a JComponent instance which will be added to the wrapped JComponent type of this builder.
      Due to the usage of the mutable the Vals property list, this method assumes your view models to be based on place oriented programming practices. Although SwingTree offers API for this style of programming, we strongly recommend using value objects for your view models and Tuples instead of Vals lists.
      See addAll(Val, ViewSupplier) as the recommended alternative to this method.
      Type Parameters:
      M - The type of the items in the Vals list.
      Parameters:
      models - A Vals list of items of any type but preferably view model instances.
      viewSupplier - A ViewSupplier instance which will be used to generate the view for each item in the list. The views will be added to the component wrapped by this builder instance.
      Returns:
      This very instance, which enables builder-style method chaining.

    • addAll

      public final <M> I addAll(String attr, sprouts.Vals<M> models, ViewSupplier<M> viewSupplier)
      This allows you to dynamically generate views for the items in a Vals property list and automatically regenerate the view when any of the items change. The type of item can be anything, but it is usually a view model instance. The ViewSupplier lambda passed to this method will receive the value of the property and is then expected to return a JComponent instance which will be added to the wrapped JComponent type of this builder.
      Due to the usage of the mutable the Vals property list, this method assumes your view models to be based on place oriented programming practices. Although SwingTree offers API for this style of programming, we strongly recommend using value objects for your view models and Tuples instead of Vals lists.
      See addAll(String, Val, ViewSupplier) as the recommended alternative to this method.
      Type Parameters:
      M - The type of the items in the Vals list.
      Parameters:
      attr - The layout information which should be used as layout constraints for the generated views.
      models - A Vals list of items of any type but preferably view model instances.
      viewSupplier - A ViewSupplier instance which will be used to generate the view for each item in the list. The views will be added to the component wrapped by this builder instance.
      Returns:
      This very instance, which enables builder-style method chaining.

    • addAll

      public final <M> I addAll(AddConstraint attr, sprouts.Vals<M> models, ViewSupplier<M> viewSupplier)
      This allows you to dynamically generate views for the items in a Vals property list and automatically regenerate the view when any of the items change. The type of item can be anything, but it is usually a view model instance. The ViewSupplier lambda passed to this method will receive the value of the property and is then expected to return a JComponent instance which will be added to the wrapped JComponent type of this builder.
      Due to the usage of the mutable the Vals property list, this method assumes your view models to be based on place oriented programming practices. Although SwingTree offers API for this style of programming, we strongly recommend using value objects for your view models and Tuples instead of Vals lists.
      See addAll(AddConstraint, Val, ViewSupplier) as the recommended alternative to this method.
      Type Parameters:
      M - The type of the items in the Vals list.
      Parameters:
      attr - The layout information which should be used as layout constraints for the generated views.
      models - A Vals list of items of any type but preferably view model instances.
      viewSupplier - A ViewSupplier instance which will be used to generate the view for each item in the list. The views will be added to the component wrapped by this builder instance.
      Returns:
      This very instance, which enables builder-style method chaining.

    • addAll

      public final <M> I addAll(sprouts.Val<sprouts.Tuple<M>> models, ViewSupplier<M> viewSupplier)
      Dynamically generate views for the items in a Tuple of items, and automatically regenerate the view when any of the items in the tuple change. The type of item can be anything, but it is usually value based view models. The ViewSupplier lambda passed to this method will be invoked with each item in the tuple and is expected to return a JComponent instance which will either be added to this UI component or replace an existing view.
      Type Parameters:
      M - The type of the items in the Tuple, which is the type of the view model.
      Parameters:
      models - A property of a Tuple of items of any type but preferably view model instances.
      viewSupplier - A ViewSupplier instance which will be used to generate the view for each item in the tuple.
      Returns:
      This very instance, which enables builder-style method chaining.

    • addAll

      public final <M> I addAll(String attr, sprouts.Val<sprouts.Tuple<M>> models, ViewSupplier<M> viewSupplier)

    • addAll

      public final <M> I addAll(AddConstraint attr, sprouts.Val<sprouts.Tuple<M>> viewables, ViewSupplier<M> viewSupplier)

    • _addViewableProps

      protected <M> void _addViewableProps(sprouts.Vals<M> models, @Nullable AddConstraint attr, swingtree.ModelToViewConverter<M> viewSupplier, C thisComponent)

    • _addViewableProps

      protected <M> void _addViewableProps(sprouts.Val<sprouts.Tuple<M>> models, @Nullable AddConstraint attr, swingtree.ModelToViewConverter<M> viewSupplier, C thisComponent)