Package swingtree.style

Class TextConf

java.lang.Object
swingtree.style.TextConf
@Immutable public final class TextConf extends Object
An immutable configuration type which holds custom text as well as placement and font properties used for rendering text onto a Swing component.
This objects is exposed inside the ComponentStyleDelegate.text(Configurator) as a way to configure custom text properties of a component as part of the style API exposed by UIForAnySwing.withStyle(Styler).

Here a simple usage example which demonstrates how to render text onto the top edge of a JPanel: 


      UI.panel()
      .withStyle(conf -> conf
          .prefSize(180, 100)
          .background(Color.CYAN)
          .text(textConf -> textConf
              .content("Hello World!")
              .placement(UI.Placement.TOP)
              .font( fontConf -> fontConf.color(Color.DARK_GRAY).size(20) )
          )
      )
In this small example you can see the usage of content(String), placement(UI.Placement) and font(Configurator). But there are much more properties available to configure the text rendering as part of the style API.

Here a full list of all available properties with their respective meaning and default values:

  • Content You can set this property through content(String). This is the actual text content that should be rendered onto the component. For richer text display with multiple styles for different parts of the text, you can also pass a sequence of StyledStrings to define the text content. Each StyledString can have its own font properties which will be resolved using the FontConf of this TextConf to be derived from.
    See content(StyledString...) and content(Tuple) for more details on how to configure the content with multiple styled strings.
    The default content is an empty Tuple of StyledStrings in which the text configuration is effectively disabled!
  • Font The FontConf object is its own rich configuration object which holds all font properties like size, style, color, etc. You can configure it through font(Configurator).
    The default font configuration is FontConf.none().
  • Clip Area The clip area is an enum the area of the component where the text should be rendered. So the text will only be visible within this area.
    You can configure it through clipTo(UI.ComponentArea).
    The default clip area is UI.ComponentArea.INTERIOR.
  • Placement Boundary The placement boundary refers to one of many rectangular bounding boxes that capture the transitional bounding lines between different UI.ComponentAreas in the box model (margin|border|padding) of a styled component.
    You can configure it through placementBoundary(UI.ComponentBoundary).
    The default placement boundary is UI.ComponentBoundary.INTERIOR_TO_CONTENT, which honors the padding of the component. If you want to ignore the padding and place the text directly after the border of the component, you can set it to UI.ComponentBoundary.BORDER_TO_INTERIOR.
  • Placement The placement is an enum which defines where the text should be placed according to the placementBoundary(UI.ComponentBoundary). You can configure it through placement(UI.Placement).
    The default placement is UI.Placement.UNDEFINED. At render time this is first resolved using the horizontal and vertical alignment from the FontConf; only when those alignments are also UI.Placement.UNDEFINED does it behave like UI.Placement.CENTER.
  • Offset The offset holds the x and y placement offset of the text. You can configure it through offset(Offset) or offset(int, int).
    The default offset is Offset.none() (0, 0). This property is great for making fine adjustments to the text placement.
    However, for a more robust alignment of the text, it is recommended to use the placement(UI.Placement) and placementBoundary(UI.ComponentBoundary) properties as a first choice.
  • Wrap Lines This is a boolean property, and it defines whether the text should be wrapped into multiple lines if the text content exceeds the width of the available space inside the component.
    You can configure it through wrapLines(boolean).
    The default value is true, which means that the text will wrap into multiple lines if it exceeds the width of the available space inside the component.
    If set to false, the text will be rendered in a single line and may overflow the component if the text content is too long.
  • Auto Preferred Height Is a boolean property which configures whether the preferred height of the styled component should be computed from the text you render onto it through this TextConf and then set as the preferred height of the component.
    This will effectively turn the preferred height of the component to a function of the component's width and the displayed text.
    It will also take full ownership of the preferred height of the component, which means that a preferred height specified elsewhere in the style configuration of the component will be ignored.
    You can configure it through autoPreferredHeight(boolean).
Use none() to access the null object of the TextConf type. It is a convenient way to represent a no-op configuration object which will not have any effect when applied to a component.

  • Field Details

    • DEFAULT_LAYER

      public static UI.Layer DEFAULT_LAYER

  • Method Details

    • content

      public TextConf content(String textString)
      Returns a new TextConf object with the given text content.
      Parameters:
      textString - The text content to be rendered onto the component.
      Returns:
      A new TextConf object with the given text content.

    • content

      public TextConf content(StyledString... styledStrings)
      Configures this TextConf object to render the supplied sequence of StyledStrings as the text content onto the component.
      Each StyledString in the sequence can have its own font properties. This allows you to render visually rich and expressive text.
      Parameters:
      styledStrings - A vararg sequence of StyledStrings which should be rendered as the text content onto the component.
      Returns:
      A new TextConf object with the given text content.
      Throws:
      NullPointerException - if the supplied styledStrings is null.

    • content

      public TextConf content(sprouts.Tuple<StyledString> styledStrings)
      Configures this TextConf object to render the supplied Tuple of StyledStrings as the text content onto the component. Each StyledString in the sequence can have its own font properties. This allows you to render visually rich and expressive text.
      Parameters:
      styledStrings - A Tuple of StyledStrings which should be rendered as the text content onto the component.
      Returns:
      A new TextConf object with the given text content.
      Throws:
      NullPointerException - if the supplied styledStrings is null.

    • content

      public TextConf content(Collection<StyledString> styledStrings)
      Configures this TextConf object to render the supplied collection of StyledStrings as the text content onto the component.
      Each StyledString in the sequence can have its own font properties. This allows you to render visually rich and expressive text.
      Parameters:
      styledStrings - A collection of StyledStrings which should be rendered as the text content onto the component.
      Returns:
      A new TextConf object with the given text content.
      Throws:
      NullPointerException - if the supplied styledStrings is null.

    • font

      public TextConf font(Configurator<FontConf> fontConfFunction)
      Returns a new TextConf object with the given font configuration defined by a configurator function which takes a FontConf object and returns an updated FontConf object with the desired font properties.
      Parameters:
      fontConfFunction - A function which takes the current font configuration and returns a new font configuration with the desired properties.
      Returns:
      A new TextConf object with the given font configuration.

    • font

      public TextConf font(Font font)
      Returns a new TextConf object with the given font.
      Parameters:
      font - The font to be used for rendering the text onto the component.
      Returns:
      A new TextConf object with the given font.

    • clipTo

      public TextConf clipTo(UI.ComponentArea clipArea)
      Returns a new TextConf object with the given clip area defined by a UI.ComponentArea enum. Text positioned outside the clip area will not be visible.
      Parameters:
      clipArea - The clip area where the text should be rendered onto the component.
      Returns:
      A new TextConf object with the given clip area.

    • placementBoundary

      public TextConf placementBoundary(UI.ComponentBoundary placementBoundary)
      Allows you to narrow down the rectangular placement area of the text in the box model of the underlying component using a UI.ComponentBoundary enum constant. The component boundaries can be thought of as rectangular bounding boxes that capture the transitional edges between different UI.ComponentAreas.
      This property ensures that the text is placed inside the transitional bounding box.

      The following placement boundaries are available:

      Parameters:
      placementBoundary - The placement boundary of the component.
      Returns:
      A new TextConf object with the given placement boundary.

    • placement

      public TextConf placement(UI.Placement placement)
      Returns an updated TextConf object with the given placement, defined by a UI.Placement enum. The placement defines where the text should be placed according to the placementBoundary(UI.ComponentBoundary).

      The following placements are available:

      Parameters:
      placement - The placement of the text, defined by a UI.Placement enum.
      Returns:
      An updated TextConf object with the desired placement.

    • offset

      public TextConf offset(int x, int y)
      Returns a TextConf object updated with an x and y placement offset. The offset holds the x and y placement offset of the text. This property is great for making fine adjustments to the text placement. However, for a more robust alignment of the text, it is recommended to use the placement(UI.Placement) and placementBoundary(UI.ComponentBoundary) properties as a first choice.
      Parameters:
      x - The x placement offset of the text.
      y - The y placement offset of the text.
      Returns:
      An updated TextConf object with the given offset.

    • wrapLines

      public TextConf wrapLines(boolean wrapLines)
      Configures whether the text should be wrapped into multiple lines if the text content exceeds the width of the available space inside the component. The default value is true, which means that the text will wrap into multiple lines if it exceeds the width of the available space inside the component.
      Parameters:
      wrapLines - A boolean value which defines whether the text should be wrapped into multiple lines.
      Returns:
      An updated TextConf object with the given wrap lines property.

    • autoPreferredHeight

      public TextConf autoPreferredHeight(boolean autoPreferredHeight)
      Configures whether the preferred height of the styled component should be computed from the text you render onto it through this TextConf and then set as the preferred height of the component.
      This will effectively turn the preferred height of the component to a function of the component's width and the displayed text.
      It will also take full ownership of the preferred height of the component, which means that a preferred height specified elsewhere in the style configuration of the component will be ignored.
      Parameters:
      autoPreferredHeight - If true, then the style engine will compute and set a preferred height for the styled component which is based on the text layout produced by this text configuration.
      Returns:
      A new text configuration with the desired auto height behavior.

    • simplified

      public TextConf simplified()

    • isNone

      public boolean isNone()

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object