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 case 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.
    Important: Note that obstacles(Shape...) are only compatible with TOP_LEFT, TOP and TOP_RIGHT! Any other placement turns off obstacle avoidance...
  • 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).
  • Obstacles A set of Shapes (in component coordinates) that the text must skip over and flow around so that it is never rendered on top of.
    You can configure it through obstacles(Shape...) or obstacles(Tuple).
    The default value is an empty Tuple, meaning no obstacles are applied, however, if a particular component with a text configuration has child components, then the bounding boxes of those child components will automatically be registered as obstacles.

    Important — placement compatibility: obstacle avoidance is only active when placement(UI.Placement) is one of UI.Placement.TOP_LEFT, UI.Placement.TOP, or UI.Placement.TOP_RIGHT. Any other placement silently disables obstacle avoidance and renders the text as if no obstacles had been registered. The reason for this restriction is architectural:

    • The algorithm flows text downward, tracking the y-coordinate of each successive line to query which horizontal intervals are free at that level. This maps cleanly only onto a layout that starts from the top and grows downward.
    • A bottom-anchored placement would require running the entire algorithm in reverse (growing upward), roughly doubling the implementation complexity.
    • A vertically centred placement creates a circular dependency: the height of the text block depends on the obstacles, but where the lines land vertically depends on the height of the text block. Resolving this correctly would require iterative convergence akin to a fluid-dynamics solver — far beyond the scope of a UI layout engine.
  • Obstacles From Children Enabled A boolean property that controls whether child components of the styled component are automatically registered as text-layout obstacles.
    When true (the default), every child contributes an obstacle shape so that the text flows around the children rather than rendering on top of them.
    When false, child components are completely ignored during obstacle collection regardless of the obstaclesFromChildren(UI.ComponentBoundary) setting.
    You can configure it through obstaclesFromChildrenEnabled(boolean).
  • Obstacles From Children A UI.ComponentBoundary property that selects which boundary layer of each child component is used as its obstacle shape when automatic child-obstacle registration is active (i.e. obstaclesFromChildrenEnabled(boolean) is true).
    Think of the boundaries as an onion peeled inward: UI.ComponentBoundary.OUTER_TO_EXTERIOR (the default) uses the full bounding rectangle of the child including any margin, while inner boundaries such as UI.ComponentBoundary.EXTERIOR_TO_BORDER or UI.ComponentBoundary.BORDER_TO_INTERIOR shrink the obstacle progressively inward, letting text flow into the child's margin or border areas respectively. Children without a SwingTree style fall back to the full bounding rectangle for any value.
    You can configure it through obstaclesFromChildren(UI.ComponentBoundary).
    If you want to disable automatic child-derived obstacles entirely, you can do so by calling obstaclesFromChildrenEnabled(false).
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:


      Also note that not all placements are compatible with the obstacles(Shape...) avoidance feature. Only TOP_LEFT, TOP and TOP_RIGHT allow for text to avoid obstacles...
      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.

    • obstacles

      public TextConf obstacles(Shape... obstacles)
      Returns an updated TextConf with the given shapes registered as "text obstacles" for the text layout engine. The text will wrap around and skip over each obstacle and can never be rendered on top of it. Obstacle shapes are specified in component coordinates.

      Curved shapes such as circles or ellipses are supported as well.
      Important — placement compatibility: obstacle avoidance is only active when placement(UI.Placement) is one of UI.Placement.TOP_LEFT, UI.Placement.TOP, or UI.Placement.TOP_RIGHT. Any other placement silently disables obstacle avoidance. See the TextConf class-level documentation for a detailed explanation of why bottom-anchored and vertically-centred placements cannot support obstacle avoidance.

      Parameters:
      obstacles - One or more Shapes in component coordinates for text to skip over.
      Returns:
      An updated TextConf with the given obstacles.

    • obstacles

      public TextConf obstacles(sprouts.Tuple<Shape> obstacles)
      Returns an updated TextConf with the given Tuple of shapes registered as "text obstacles" for the text layout engine. The text will wrap around and skip over each obstacle and can never be rendered on top of it. Obstacle shapes are specified in component coordinates.

      Curved shapes such as circles or ellipses are supported as well.
      Important — placement compatibility: obstacle avoidance is only active when placement(UI.Placement) is one of UI.Placement.TOP_LEFT, UI.Placement.TOP, or UI.Placement.TOP_RIGHT. Any other placement silently disables obstacle avoidance. See the TextConf class-level documentation for a detailed explanation of why bottom-anchored and vertically-centred placements cannot support obstacle avoidance.

      Parameters:
      obstacles - A Tuple of Shapes in component coordinates for text to skip over.
      Returns:
      An updated TextConf with the given obstacles.

    • obstaclesFromChildren

      public TextConf obstaclesFromChildren(UI.ComponentBoundary boundary)
      Configures which boundary layer of each child component should be used when automatically deriving text-layout obstacles from the parent component's children.

      When a styled component has child components, the style engine automatically collects a shape for each child and registers it as an obstacle for the text layout, so that the text flows around the children rather than rendering on top of them.

      Think of the boundaries as an onion peeled inward — each boundary defines how far inside a child the obstacle extends. The available values are:

      Child components that do not carry a SwingTree style (i.e. plain Swing components without margin or border styling) always fall back to the full bounding rectangle.
      Parameters:
      boundary - The component boundary of each child that should be treated as an obstacle.
      Returns:
      An updated TextConf with the given child-obstacle boundary setting.

    • obstaclesFromChildrenEnabled

      public TextConf obstaclesFromChildrenEnabled(boolean enabled)
      Controls whether the style engine should automatically register child components of the parent as text-layout obstacles for this text configuration.

      When set to true (the default), the style engine collects the bounding shape of every child component and adds it to the text obstacles, so that the rendered text flows around the children rather than overlapping them. The exact portion of each child that is treated as an obstacle can be refined with obstaclesFromChildren(UI.ComponentBoundary).

      When set to false, child components are completely ignored during obstacle collection. This is useful when you deliberately want text and child components to share the same visual area — for example when a child is a transparent overlay or a decorative element that should not interrupt the text flow.

      Parameters:
      enabled - true to enable automatic child-obstacle registration (the default), false to disable it entirely.
      Returns:
      An updated TextConf with the given child-obstacle-enabled setting.

    • 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