Package swingtree

Class UIForLabel<L extends JLabel>

java.lang.Object
swingtree.UIForAnything<UIForLabel<L>,L,JComponent>
swingtree.UIForAnySwing<UIForLabel<L>,L>
swingtree.UIForLabel<L>
Type Parameters:
L - The type of JLabel that this UIForLabel is configuring.
public final class UIForLabel<L extends JLabel> extends UIForAnySwing<UIForLabel<L>,L>
A SwingTree builder node designed for configuring JLabel instances.

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.

  • Method Details

    • _state

      protected swingtree.BuilderState<L> _state()
      Description copied from class: UIForAnything
      Returns the state of the builder, which is a container for the wrapped component as well as it's type and current EventProcessor.
      Specified by:
      _state in class UIForAnything<UIForLabel<L extends JLabel>,L extends JLabel,JComponent>
      Returns:
      The state of the builder.

    • _newBuilderWithState

      protected UIForLabel<L> _newBuilderWithState(swingtree.BuilderState<L> newState)
      Description copied from class: UIForAnything
      An internal wither method which creates a new builder instance with the provided BuilderState stored inside it.
      Specified by:
      _newBuilderWithState in class UIForAnything<UIForLabel<L extends JLabel>,L extends JLabel,JComponent>
      Parameters:
      newState - The new state which should be stored inside the new builder instance.
      Returns:
      A new builder instance with the provided state stored inside it.

    • makeBold

      public UIForLabel<L> makeBold()
      Makes the wrapped JLabel font bold (!plain).

      Note that this is an additive operation: it only switches the bold bit of the current font on and leaves every other style bit untouched. So a label whose font is already italic will end up bold and italic. This differs from withFontStyle(UI.FontStyle), which replaces the style completely, so withFontStyle(UI.FontStyle.BOLD) would clear the italic bit instead of preserving it.

      Returns:
      This very builder to allow for method chaining.

    • makeLinkTo

      public UIForLabel<L> makeLinkTo(String href)
      Use this to make the underlying JLabel into a clickable link.
      Parameters:
      href - A string containing a valid URL used as link hyper reference.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if href is null.

    • makeLinkTo

      public UIForLabel<L> makeLinkTo(sprouts.Val<String> href)
      Use this to make the underlying JLabel into a clickable link based on the string provided property defining the link address. When the link wrapped by the provided property changes, then a click on the label will lead to the wrapped link.
      Parameters:
      href - A string property containing a valid URL used as link hyper reference.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if href is null.

    • withFontStyle

      public UIForLabel<L> withFontStyle(UI.FontStyle style)
      Adjusts the style bits of the wrapped JLabel's font so that it matches the supplied UI.FontStyle, which may be any of UI.FontStyle.PLAIN, UI.FontStyle.BOLD, UI.FontStyle.ITALIC or UI.FontStyle.BOLD_ITALIC.

      Only the style of the font is replaced; the font family and size of the label are preserved. So for a label whose font is currently italic, calling withFontStyle(UI.FontStyle.BOLD) will turn it into a (non-italic) bold font, whereas withFontStyle(UI.FontStyle.BOLD_ITALIC) would make it both bold and italic: 

      
      UI.label("Important!")
      .withFontStyle(UI.FontStyle.BOLD_ITALIC);
      For the common case of toggling between bold and plain you may also use the dedicated makeBold() and makePlain() shorthands. Be aware, however, that those shorthands behave additively (they flip only the bold bit and preserve the rest), whereas this method replaces the entire style. So withFontStyle(UI.FontStyle.BOLD) clears a previously set italic bit, while makeBold() would keep it.
      Parameters:
      style - The UI.FontStyle which should be applied to the font of the label.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if style is null.

    • withFontStyle

      public UIForLabel<L> withFontStyle(sprouts.Val<UI.FontStyle> style)
      Dynamically adjusts the style bits of the wrapped JLabel's font based on the UI.FontStyle wrapped by the provided property. When the style enum wrapped by the property changes, then so does the style of the label's font change to match it. This is useful for modelling the font style as part of your view model so that the appearance of the label can react to your business logic at runtime: 
      
      // A property somewhere in your view model:
      Var<UI.FontStyle> style = Var.of(UI.FontStyle.PLAIN);
      // ...and in your view:
      UI.label("Status")
      .withFontStyle(style);
      // Later on, changing the property updates the label:
      style.set(UI.FontStyle.BOLD_ITALIC);
      The supported UI.FontStyle values are UI.FontStyle.PLAIN, UI.FontStyle.BOLD, UI.FontStyle.ITALIC and UI.FontStyle.BOLD_ITALIC. Note that, just like with withFontStyle(UI.FontStyle), the style of the font is replaced completely on every change (the font family and size of the label are preserved). This is in contrast to the makeBold() and makePlain() shorthands, which only flip the bold bit additively and leave any other style bit, like italic, intact.
      Parameters:
      style - The UI.FontStyle property which should be applied to the font of the label.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if style is null.

    • makePlain

      public UIForLabel<L> makePlain()
      Makes the wrapped JLabel font plain (!bold).

      Note that this is an additive operation: it only switches the bold bit of the current font off and leaves every other style bit untouched. So a label whose font is bold and italic will remain italic (just no longer bold). This differs from withFontStyle(UI.FontStyle), which replaces the style completely, so withFontStyle(UI.FontStyle.PLAIN) would clear the italic bit as well, yielding a fully plain font.

      Returns:
      This very builder to allow for method chaining.

    • toggleBold

      public final UIForLabel<L> toggleBold()
      Makes the wrapped JLabel font bold if it is plain and plain if it is bold...
      Returns:
      This very builder to allow for method chaining.

    • isBoldIf

      public final UIForLabel<L> isBoldIf(boolean isBold)
      Makes the wrapped JLabel font bold if the provided flag is true, and plain if the flag is false. See makeBold() and makePlain() for more information.
      Parameters:
      isBold - The flag determining if the font of this label should be bold or plain.
      Returns:
      This very builder to allow for method chaining.

    • isBoldIf

      public final UIForLabel<L> isBoldIf(sprouts.Val<Boolean> isBold)
      When the flag wrapped by the provided property changes, then the font of this label will switch between being bold and plain.
      Parameters:
      isBold - The property which should be bound to the boldness of this label.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if isBold is null.

    • withText

      public final UIForLabel<L> withText(String text)
      Defines the single line of text this component will display. If the value of text is null or empty string, nothing is displayed.

      The default value of this property is null.

      Parameters:
      text - The new text to be set for the wrapped label.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if text is null.

    • withText

      public final UIForLabel<L> withText(sprouts.Val<String> text)
      Dynamically defines a single line of text displayed on this label. If the value of text is null or an empty string, nothing is displayed. When the text wrapped by the provided property changes, then so does the text displayed on this label change.
      Parameters:
      text - The text property to be bound to the wrapped label.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if text is null.

    • withHorizontalAlignment

      public UIForLabel<L> withHorizontalAlignment(UI.HorizontalAlignment horizontalAlign)
      A convenience method to avoid peeking into this builder like so: 
      
     UI.label("Something")
     .peek( label -> label.setHorizontalAlignment(...) );
      This sets the horizontal alignment of the label's content (icon and text).
      Parameters:
      horizontalAlign - The horizontal alignment which should be applied to the underlying component.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if horizontalAlign is null.

    • withHorizontalAlignment

      public UIForLabel<L> withHorizontalAlignment(sprouts.Val<UI.HorizontalAlignment> horizontalAlign)
      This binds to a property defining the horizontal alignment of the label's content (icon and text). When the alignment enum wrapped by the provided property changes, then so does the alignment of this label.
      Parameters:
      horizontalAlign - The horizontal alignment property which should be applied to the underlying component.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if horizontalAlign is null.

    • withVerticalAlignment

      public UIForLabel<L> withVerticalAlignment(UI.VerticalAlignment verticalAlign)
      Use this to set the vertical alignment of the label's content (icon and text). This is a convenience method to avoid peeking into this builder like so: 
      
     UI.label("Something")
     .peek( label -> label.setVerticalAlignment(...) );
      Parameters:
      verticalAlign - The vertical alignment which should be applied to the underlying component.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if verticalAlign is null.

    • withVerticalAlignment

      public UIForLabel<L> withVerticalAlignment(sprouts.Val<UI.VerticalAlignment> verticalAlign)
      This binds to a property defining the vertical alignment of the label's content (icon and text). When the alignment enum wrapped by the provided property changes, then so does the alignment of this label.
      Parameters:
      verticalAlign - The vertical alignment property which should be applied to the underlying component.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if verticalAlign is null.

    • withAlignment

      public UIForLabel<L> withAlignment(UI.Alignment alignment)
      Use this to set the horizontal and vertical alignment of the label's content (icon and text). This is a convenience method to avoid peeking into this builder like so: 
      
     UI.label("Something")
     .peek( label -> label.setHorizontalAlignment(...); label.setVerticalAlignment(...) );
      Parameters:
      alignment - The alignment which should be applied to the underlying component.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if alignment is null.

    • withAlignment

      public UIForLabel<L> withAlignment(sprouts.Val<UI.Alignment> alignment)
      This binds to a property defining the horizontal and vertical alignment of the label's content (icon and text). When the alignment enum wrapped by the provided property changes, then so does the alignment of this label.
      Parameters:
      alignment - The alignment property which should be applied to the underlying component.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if alignment is null.

    • withHorizontalTextPosition

      public UIForLabel<L> withHorizontalTextPosition(UI.HorizontalAlignment horizontalAlign)
      Use this to set the horizontal position of the label's text, relative to its image. A convenience method to avoid peeking into this builder like so: 
      
     UI.label("Something")
         .peek( label -> label.setHorizontalTextPosition(...) );
      Parameters:
      horizontalAlign - The horizontal alignment which should be applied to the text of the underlying component.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if horizontalAlign is null.

    • withHorizontalTextPosition

      public UIForLabel<L> withHorizontalTextPosition(sprouts.Val<UI.HorizontalAlignment> horizontalAlign)
      Use this to bind to a property defining the horizontal position of the label's text, relative to its image. When the alignment enum wrapped by the provided property changes, then so does the alignment of this label.
      Parameters:
      horizontalAlign - The horizontal alignment property which should be applied to the text of the underlying component.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if horizontalAlign is null.

    • withVerticalTextPosition

      public UIForLabel<L> withVerticalTextPosition(UI.VerticalAlignment verticalAlign)
      Use this to set the horizontal position of the label's text, relative to its image.
      This is a convenience method to avoid peeking into this builder like so: 
      
     UI.label("Something")
     .peek( label -> label.setVerticalTextPosition(...) );
      Parameters:
      verticalAlign - The vertical alignment which should be applied to the text of the underlying component.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if verticalAlign is null.

    • withVerticalTextPosition

      public UIForLabel<L> withVerticalTextPosition(sprouts.Val<UI.VerticalAlignment> verticalAlign)
      Use this to bind to a property defining the vertical position of the label's text, relative to its image. When the alignment enum wrapped by the provided property changes, then so does the alignment of this label.
      Parameters:
      verticalAlign - The vertical alignment property which should be applied to the text of the underlying component.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if verticalAlign is null.

    • withTextPosition

      public UIForLabel<L> withTextPosition(UI.Alignment alignment)
      Use this to set the horizontal and vertical position of the label's text, relative to its image. This is a convenience method to avoid peeking into this builder like so: 
      
     UI.label("Something")
         .peek( label -> label.setHorizontalTextPosition(...); label.setVerticalTextPosition(...) );
      Parameters:
      alignment - The alignment which should be applied to the text of the underlying component.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if alignment is null.

    • withIcon

      public UIForLabel<L> withIcon(Icon icon)
      Use this to set the icon for the wrapped JLabel. This is in essence a convenience method to avoid peeking into this builder like so: 
      
     UI.label("Something")
         .peek( label -> label.setIcon(...) );
      Parameters:
      icon - The Icon which should be displayed on the label.
      Returns:
      This very builder to allow for method chaining.

    • withIcon

      public UIForLabel<L> withIcon(IconDeclaration icon)
      Use this to set the icon for the wrapped JLabel based on the provided IconDeclaration.

      An IconDeclaration should be preferred over the Icon class as part of a view model, because it is a lightweight value object that merely models the resource location of the icon even if it is not yet loaded or even does not exist at all.

      Parameters:
      icon - The IconDeclaration which should be displayed on the label.
      Returns:
      This very builder to allow for method chaining.

    • withIcon

      public UIForLabel<L> withIcon(sprouts.Val<IconDeclaration> icon)
      Use this to dynamically set the icon property for the wrapped JLabel. When the icon wrapped by the provided property changes, then so does the icon of this label.

      But note that you may not use the Icon or ImageIcon classes directly, instead you must use implementations of the IconDeclaration interface, which merely models the resource location of the icon, but does not load the whole icon itself.

      The reason for this distinction is the fact that traditional Swing icons are heavy objects whose loading may or may not succeed, and so they are not suitable for direct use in a property as part of your view model. Instead, you should use the IconDeclaration interface, which is a lightweight value object that merely models the resource location of the icon even if it is not yet loaded or even does not exist at all.

      This is especially useful in case of unit tests for you view model, where the icon may not be available at all, but you still want to test the behaviour of your view model.

      Parameters:
      icon - The Icon property which should be displayed on the label.
      Returns:
      This very builder to allow for method chaining.
      Throws:
      IllegalArgumentException - if icon is null.