Package swingtree.style

Class FontConf

java.lang.Object
swingtree.style.FontConf
@Immutable public final class FontConf extends Object
An immutable, wither-like method based config API for font styles that is part of the full StyleConf configuration object.

The following properties with their respective purpose are available:

  1. Name

    The name of the font, which is essentially the font family. This will ultimately translate to Font.getFamily().
    You may specify the font family name through the family(String) method.

  2. Size

    The size of the font in points, which will ultimately translate to Font.getSize(). Use the size(int) method to specify the size of the font.

  3. Posture

    The posture of the font, which is a value between 0 and 1.
    A value of 0 means that the font is not italic, while a value of 1 means that the font is "fully" italic.
    You can use the posture(float) method to specify the posture of the font.

  4. Weight

    The weight of the font (boldness, see Font.BOLD), which is a value between 0 and 2.

    The weight of the font can be specified using the weight(double) method.

  5. Spacing (Tracking)

    This property controls the tracking which is a floating point number with the default value of 0, meaning no additional tracking is added to the font.

    Useful constant values are the predefined TextAttribute.TRACKING_TIGHT and TextAttribute.TRACKING_LOOSE values, which represent values of -0.04 and 0.04,

    The tracking value is multiplied by the font point size and passed through the font transform to determine an additional amount to add to the advance of each glyph cluster. Positive tracking values will inhibit formation of optional ligatures. Tracking values are typically between -0.1 and 0.3; values outside this range are generally not desirable.

    You can use the spacing(float) method to specify the tracking of the font.

  6. Color

    The color of the font, which translates to the text property TextAttribute.FOREGROUND.

    You can use the color(Color) or color(String) methods to specify the color of the font.

  7. Background Color

    The background color of the font which translates to the text property TextAttribute.BACKGROUND.

  8. Selection Color

    The selection color of the font, which translates to JTextComponent.setSelectionColor(Color).
    Note that this property is only relevant for text components, most components do not support text selection.

  9. Underlined

    Whether or not the font is underlined. This will ultimately translate to TextAttribute.UNDERLINE.

  10. Strike

    Whether or not the font is strike through. This will ultimately translate to TextAttribute.STRIKETHROUGH.

  11. Transform

    The transform of the font, which is an AffineTransform instance.

  12. Paint

    The paint of the font, which is a Paint instance. Note that specifying a custom paint will override the effects of the color property as the color property is in essence merely a convenience property for a paint painting across the entire font area homogeneously using the specified color.

  13. Background Paint

    The background paint of the font, which is a Paint instance that is used to paint the background of the font.

  14. Horizontal Alignment

    The horizontal alignment of the font.
    Note that this property is not relevant for all components, It will usually only be relevant for JLabel, AbstractButton and JTextField types or maybe some custom components. Not all components support horizontal alignment.

  15. Vertical Alignment

    The vertical alignment of the font.
    Note that this property is not relevant for all components, It will usually only be relevant for JLabel, AbstractButton and JTextField types or maybe some custom components. Not all components support vertical alignment.

You can use the none() method to specify that no font should be used, as the instance returned by that method is a font style with an empty string as its name, and other properties set to their default values, effectively making it a representation of the absence of a font style.

Also note that this class is immutable, which means that wither-like methods will always return new instances of this class, leaving the original instance untouched.
This means that you can not modify a font style instance directly, but you can easily create a modified copy of it by calling one of the wither-like methods.

  • Method Details

    • none

      public static FontConf none()
      Returns a font style with all properties set to their no-op default values, effectively making it a representation of the absence of a font style.
      Returns:
      A font style with all properties set to no-op default values.

    • family

      public String family()
      Returns the font family name for this font configuration. This corresponds to the Font.getFamily() property in Font and determines the visual style category of the typeface.

      The font family represents a group of related typefaces that share common design characteristics but may vary in weight, style, or other attributes. Common examples include:

      • "Arial" - A clean, sans-serif font
      • "Times New Roman" - A classic serif font
      • "Courier New" - A monospaced font
      • "Verdana" - A sans-serif font designed for screen readability

      From a user perspective, the font family defines the overall visual personality of the text.

      Returns:
      The font family name as a String. Returns an empty string if no specific family is defined, which typically means the system default font family should be used.
      See Also:

    • size

      public int size()
      Returns the font size in points for this font configuration. This corresponds to the Font.getSize() property in Font and determines the visual height of the text characters.

      In typography, a "point" is a physical unit of measurement where 1 point equals 1/72 of an inch. However, in digital typography, the actual rendered size may vary based on screen resolution, display density (DPI), and the current UI scaling factor.

      The perceived size may also be influenced by the specific font family, as some typefaces appear larger than others at the same point size due to differences in x-height and character proportions.

      Returns:
      The font size in points. Returns 0 if no specific size is defined, which typically means the system default font size should be used.
      See Also:

    • posture

      public Optional<Float> posture()
      Returns the posture (italic) attribute of this font configuration. This corresponds to the TextAttribute.POSTURE property and influences whether the font appears in regular upright or italic (slanted) form.

      The posture is represented as a floating-point value where:

      • 0.0 - Regular upright posture (non-italic)
      • 0.2 - Standard italic posture
      • Values between 0.0 and 0.2 represent varying degrees of slant

      From a user perspective, italic text serves several purposes:

      • Emphasis - Drawing attention to specific words or phrases within a body of text
      • Distinction - Differentiating certain types of content, such as book titles, foreign words, or technical terms
      • Visual variety - Adding stylistic variation to break visual monotony
      • Hierarchy - Creating subtle visual distinctions in complex layouts

      It's important to note that true italic fonts are specifically designed with unique character shapes, while oblique fonts are simply slanted versions of the regular font. The visual quality depends on whether the font family includes dedicated italic variants.

      Returns:
      An Optional containing the posture value if defined, or empty if no specific posture is configured (system default should be used).
      See Also:

    • weight

      public Optional<Float> weight()
      Returns the weight (boldness) attribute of this font configuration. This corresponds to the TextAttribute.WEIGHT property and determines the thickness of the character strokes.

      The weight is represented as a floating-point value where:

      • 0.0 - Light weight (thin strokes)
      • 1.0 - Regular/standard weight (equivalent to Font.PLAIN)
      • 2.0 - Bold weight (equivalent to Font.BOLD)
      • Values between these represent intermediate weights (semibold, etc.)

      The actual availability of different weights depends on the font family. Some families only support regular and bold, while professional typefaces may offer multiple weights from thin to black.

      Returns:
      An Optional containing the weight value if defined, or empty if no specific weight is configured (system default should be used).
      See Also:

    • spacing

      public float spacing()
      Returns the character spacing (tracking) attribute of this font configuration. This corresponds to the TextAttribute.TRACKING property and controls the uniform adjustment of space between characters.

      The spacing value is a multiplier that affects the space between all characters:

      • 0.0 - Normal, font-default spacing
      • Negative values (-0.04 to 0.0) - Tighter spacing, characters are closer together
      • Positive values (0.0 to 0.04) - Looser spacing, characters are farther apart

      Useful predefined constants include:

      Typical values range from -0.1 to 0.3, with values outside this range generally producing undesirable results for continuous text. Tighter spacing can make text feel denser and more compact, while looser spacing can improve legibility, especially at small sizes or for users with visual impairments

      Returns:
      The character spacing value. Returns 0.0 if normal, font-default spacing should be used.
      See Also:

    • selectionColor

      public Optional<Color> selectionColor()
      Returns the text selection color for this font configuration. This property is specifically relevant for text components that support user text selection, such as JTextField, JTextArea, and JTextPane.

      The selection color determines the background color applied to text when users highlight it with mouse dragging or keyboard navigation. This visual feedback is crucial for indicating which text is currently selected for operations like copy, cut, or formatting changes.

      This property typically maps to component methods like JTextComponent.setSelectionColor(Color). When not specified, components use their default selection colors, which are often derived from the current look and feel or system preferences.

      Returns:
      An Optional containing the selection Color if defined, or empty if no specific selection color is configured (component default should be used).
      See Also:

    • isUnderlined

      public boolean isUnderlined()
      Returns whether the font should be rendered with an underline. This corresponds to the TextAttribute.UNDERLINE property and controls the presence of a horizontal line beneath the text baseline.

      The underline is a binary attribute - text is either underlined or not. When enabled, a continuous line is drawn below the text characters, typically positioned to avoid descending characters (like 'g', 'j', 'p', 'q', 'y').

      It's important to use underlining judiciously, as excessive use can reduce readability and create visual noise. In modern UI design, underlining is primarily reserved for link identification.

      Returns:
      true if the font should be rendered with an underline, false if no underline should be applied. Returns the default value (false) if no specific underline preference is configured.
      See Also:

    • horizontalAlignment

      public UI.HorizontalAlignment horizontalAlignment()
      The horizontal alignment of a font configuration is an enum constant which express how text should be positioned within components that support text alignment in terms of left/right/center positioning along the x-axis.

      Component Support Limitations:
      Note that horizontal alignment is only applicable to specific Swing components that expose alignment methods or other means of styling, such as:

      This property will have no effect on components that don't support text alignment, except for when you use this property to render text through the SwingTree style API (see UIForAnySwing.withStyle(Styler)).
      Returns:
      The horizontal alignment constant of this conf, which may be NONE, LEFT, CENTER, RIGHT... among others.

    • verticalAlignment

      public UI.VerticalAlignment verticalAlignment()
      The vertical alignment of a font configuration is an enum constant which express how text should be positioned within components that support text alignment in terms of top/bottom/center positioning along the y-axis.

      Component Support Limitations:
      Note that vertical alignment is only applicable to specific Swing components that expose alignment methods or other means of styling, such as:

      This property will have no effect on components that don't support text alignment, except for when you use this property to render text through the SwingTree style API (see UIForAnySwing.withStyle(Styler)).
      Returns:
      The vertical alignment constant of this conf, which may be NONE, TOP, CENTER, BOTTOM... among others.

    • family

      public FontConf family(String fontFamily)
      Returns an updated font config with the specified font family name.
      Parameters:
      fontFamily - The font family name to use for the Font.getFamily() property.
      Returns:
      A new font style with the specified font family name.

    • size

      public FontConf size(int fontSize)
      Returns an updated font config with the specified font size, which will translate to a Font instance with the specified size (see Font.getSize()).
      Parameters:
      fontSize - The font size to use for the Font.getSize() property.
      Returns:
      A new font style with the specified font size.

    • posture

      public FontConf posture(float posture)
      Returns an updated font config with the specified posture, defining the tilt of the font. A Font with a higher posture value will be more italic. (see Font.isItalic()).
      Parameters:
      posture - The posture to use for the Font.isItalic() property.
      Returns:
      A new font style with the specified posture.

    • weight

      public FontConf weight(double fontWeight)
      Returns an updated font config with the specified weight, defining the boldness of the font. A Font with a higher weight value will be bolder. (see Font.isBold()).
      Parameters:
      fontWeight - The weight to use for the Font.isBold() property.
      Returns:
      A new font style with the specified weight.

    • style

      public FontConf style(UI.FontStyle fontStyle)
      Determines if the font should be plain, bold, italic or bold and italic based on the provided UI.FontStyle parameter, which may be UI.FontStyle.PLAIN, UI.FontStyle.BOLD, UI.FontStyle.ITALIC or UI.FontStyle.BOLD_ITALIC.
      Note that this will override any previous bold or italic settings.
      Parameters:
      fontStyle - The font style to use for the font in the UI.FontStyle enum.
      Returns:
      An updated font config with the specified font style.

    • spacing

      public FontConf spacing(float spacing)
      Returns an updated font config with the specified spacing, defining the tracking of the font. The tracking value is multiplied by the font point size and passed through the font transform to determine an additional amount to add to the advance of each glyph cluster. Positive tracking values will inhibit formation of optional ligatures. Tracking values are typically between -0.1 and 0.3; values outside this range are generally not desirable.
      Parameters:
      spacing - The spacing to use for the TextAttribute.TRACKING property.
      Returns:
      A new font style with the specified spacing.

    • color

      public FontConf color(Color color)
      Returns an updated font config with the specified color, which will be used for the TextAttribute.FOREGROUND property of the resulting Font instance.
      Parameters:
      color - The color to use for the TextAttribute.FOREGROUND property.
      Returns:
      A new font style with the specified color.

    • color

      public FontConf color(String colorString)
      Returns an updated font config with the specified color string used to define the font color. The color will be used for the TextAttribute.FOREGROUND property of the resulting Font instance.
      Parameters:
      colorString - The color string to use for the TextAttribute.FOREGROUND property.
      Returns:
      A new font style with the specified color.

    • backgroundColor

      public FontConf backgroundColor(Color backgroundColor)
      Returns an updated font config with the specified background color. The color value will be used for the TextAttribute.BACKGROUND property of the resulting Font instance.
      Parameters:
      backgroundColor - The background color to use for the TextAttribute.BACKGROUND property.
      Returns:
      A new font style with the specified background color.

    • backgroundColor

      public FontConf backgroundColor(String colorString)
      Returns an updated font config with the specified background color string used to define the background color. The background color will be used for the TextAttribute.BACKGROUND property of the resulting Font instance.
      Parameters:
      colorString - The color string to use for the TextAttribute.BACKGROUND property.
      Returns:
      A new font style with the specified background color.

    • selectionColor

      public FontConf selectionColor(Color selectionColor)
      Returns an updated font config with the specified selection color. The selection color will be used for the selection color of the font. Note that not all components support text selection, so this property may not have an effect on all components.
      Parameters:
      selectionColor - The selection color to use for the selection color of the font.
      Returns:
      A new font style with the specified selection color.

    • selectionColor

      public FontConf selectionColor(String colorString)
      Returns an updated font config with the specified selection color string used to define the selection color. The selection color will be used for the selection color of the font. Note that not all components support text selection, so this property may not have an effect on all components.
      Parameters:
      colorString - The color string to use for the selection color of the font.
      Returns:
      A new font style with the specified selection color.

    • underlined

      public FontConf underlined(boolean underlined)
      Returns an updated font config with the specified underlined property. This boolean will translate to the TextAttribute.UNDERLINE property of the resulting Font instance.
      Parameters:
      underlined - Whether the font should be underlined.
      Returns:
      A new font style with the specified underlined property.

    • strikeThrough

      public FontConf strikeThrough(boolean strike)
      Returns an updated font config with the specified strike through property. This boolean will translate to the TextAttribute.STRIKETHROUGH property of the resulting Font instance.
      Parameters:
      strike - Whether the font should be strike through.
      Returns:
      A new font style with the specified strike through property.

    • transform

      public FontConf transform(@Nullable AffineTransform transform)
      Returns an updated font config with the specified transform. This transform will be used for the TextAttribute.TRANSFORM property of the resulting Font instance.
      Parameters:
      transform - The transform to use for the TextAttribute.TRANSFORM property.
      Returns:
      A new font style with the specified transform.

    • paint

      public FontConf paint(@Nullable Paint paint)
      Returns an updated font config with the specified paint. This paint will be used for the TextAttribute.FOREGROUND property of the resulting Font instance. Note that specifying a custom paint will override the effects of the color property as the color property is in essence merely a convenience property for a paint painting across the entire font area homogeneously using the specified color.
      Note that this will override the effects of the color(Color), color(String), noise(Configurator) or gradient(Configurator) methods as a font can only have one paint.
      Parameters:
      paint - The paint to use for the TextAttribute.FOREGROUND property.
      Returns:
      A new font style with the specified paint.

    • noise

      public FontConf noise(Configurator<NoiseConf> configurator)
      Configures a noise function based Paint for the font appearance, using a configurator function that takes a NoiseConf instance and returns an updated NoiseConf instance with the desired properties.
      Keep in mind that this will override the effects of the color(Color), color(String), paint(Paint) or gradient(Configurator) methods as a font can only have one paint.
      Parameters:
      configurator - The configurator function that takes a NoiseConf instance and returns an updated NoiseConf instance with the desired properties.
      Returns:
      A new font style with the specified noise paint.

    • gradient

      public FontConf gradient(Configurator<GradientConf> configurator)
      Configures a gradient function based Paint for the font appearance, using a configurator function that takes a GradientConf instance and returns an updated GradientConf instance with the desired properties.
      Keep in mind that this will override the effects of the color(Color), color(String), paint(Paint) or noise(Configurator) methods as a font can only have one paint.
      Parameters:
      configurator - The configurator function that takes a GradientConf instance and returns an updated GradientConf instance with the desired properties.
      Returns:
      A new font style with the specified gradient paint.

    • backgroundPaint

      public FontConf backgroundPaint(@Nullable Paint backgroundPaint)
      Returns an updated font config with the specified background paint. This paint will be used for the TextAttribute.BACKGROUND property of the resulting Font instance.
      Parameters:
      backgroundPaint - The background paint to use for the TextAttribute.BACKGROUND property.
      Returns:
      A new font style with the specified background paint.

    • backgroundNoise

      public FontConf backgroundNoise(Configurator<NoiseConf> configurator)
      Configures a noise function based Paint for the background of the font appearance, using a configurator function that takes a NoiseConf instance and returns an updated NoiseConf instance with the desired properties.
      Note that the background can only have one paint, so specifying a noise based paint will override the effects of the backgroundPaint(Paint), backgroundGradient(Configurator), and backgroundColor(String) methods.
      Parameters:
      configurator - The configurator function that takes a NoiseConf instance and returns an updated NoiseConf instance with the desired properties.
      Returns:
      A new font style with the specified noise background paint.

    • backgroundGradient

      public FontConf backgroundGradient(Configurator<GradientConf> configurator)
      Configures a gradient function based Paint for the background of the font appearance, using a configurator function that takes a GradientConf instance and returns an updated GradientConf instance with the desired properties.
      The background of a font can only have one paint, so specifying a gradient based paint will override the effects of the backgroundPaint(Paint), backgroundNoise(Configurator), and backgroundColor(String) methods.
      Parameters:
      configurator - The configurator function that takes a GradientConf instance and returns an updated GradientConf instance with the desired properties.
      Returns:
      A new font style with the specified gradient background paint.

    • horizontalAlignment

      public FontConf horizontalAlignment(UI.HorizontalAlignment horizontalAlignment)
      Returns an updated font config with the specified horizontal alignment policy, that expresses text to be placed in certain positions alongside the horizontal axis. This property is not relevant for all components, as it can only be applied to methods like JLabel.setHorizontalAlignment(int) AbstractButton.setHorizontalAlignment(int) and JTextField.setHorizontalAlignment(int), which not all components have. You can specify this horizontal text alignment property effectively through the ComponentStyleDelegate.fontAlignment(UI.VerticalAlignment) or through the FontConf in a UI.Font passed to methods like UIForAnySwing.withFont(UI.Font) or UIForAnySwing.withFont(Val).
      Parameters:
      horizontalAlignment - The horizontal alignment to use for the font.
      Returns:
      A new font style with the specified horizontal alignment.
      Throws:
      NullPointerException - if the supplied enum constant is null.

    • verticalAlignment

      public FontConf verticalAlignment(UI.VerticalAlignment verticalAlignment)
      Returns an updated font config with the specified vertical alignment policy, that * expresses text to be placed in certain positions alongside the certical axis. This property is not relevant for all components, as it can only be applied to methods like JLabel.setVerticalAlignment(int) and AbstractButton.setVerticalAlignment(int), which not all components have! You can specify this property effectively through the ComponentStyleDelegate.fontAlignment(UI.VerticalAlignment) or through the FontConf in a UI.Font passed to methods like UIForAnySwing.withFont(UI.Font) or UIForAnySwing.withFont(Val).
      Parameters:
      verticalAlignment - The vertical alignment to use for the font.
      Returns:
      A new font style with the specified vertical alignment.
      Throws:
      NullPointerException - if the supplied enum constant is null.

    • alignment

      public FontConf alignment(UI.Alignment alignment)
      Returns a new font configuration with both horizontal and vertical alignment policies specified through a unified alignment object. This method provides a convenient way to set both alignment dimensions simultaneously while ensuring consistency between horizontal and vertical alignment settings.

      The alignment properties control how text is positioned within components that support text alignment. The horizontal alignment determines left/right/center positioning along the x-axis, while vertical alignment controls top/bottom/center positioning along the y-axis.

      Component Support Limitations:
      Note that alignment properties are only applicable to specific Swing components that expose alignment methods, such as:

      This property will have no effect on components that don't support text alignment, except for when you use this property to render text through the SwingTree style API. (see ComponentStyleDelegate.fontAlignment(UI.Alignment))

      Recommended Usage:
      For effective alignment specification, use either:

      Parameters:
      alignment - The unified alignment object containing both horizontal and vertical alignment specifications. Must not be null.
      Returns:
      A new FontConf instance with the specified horizontal and vertical alignment properties applied, preserving all other font attributes from the current configuration.
      Throws:
      NullPointerException - if the provided alignment parameter is null.
      NullPointerException - if the supplied enum constant is null.
      See Also:

    • withPropertiesFromFont

      public FontConf withPropertiesFromFont(Font font)
      Creates a new FontConf instance by extracting the font properties from the provided Font instance.
      Parameters:
      font - The Font instance to extract the properties from.
      Returns:
      A new FontConf instance with the extracted properties.
      Throws:
      NullPointerException - if the provided font is null.

    • toAwtFont

      public Font toAwtFont()
      Creates a new Font instance based on this font config, using the default system font as the base font.
      Returns:
      A new Font instance based on this font config.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

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

    • toString

      public String toString()
      Overrides:
      toString in class Object