Package swingtree

Class SwingTree

java.lang.Object
swingtree.SwingTree
public final class SwingTree extends Object
A SwingTree is a singleton that holds global configuration context for the SwingTree library. This includes the EventProcessor that is used to process events, as well as the StyleSheet that is used to style components.
You may access the singleton instance of the SwingTree class through the get() method.

  • Method Summary

    Modifier and Type
    Method
    Description
    Font
    applyScaleAsFontSize(Font font)
    Converts the current scale factor given in system property "swingtree.uiScale" to a font size and then returns a new font derived from the provided one, with that new size!
    static void
    clear()
    Clears the singleton instance of the SwingTree.
    sprouts.Viewable<Float>
    createAndGetUiScaleView()
    Creates and returns a reactive Viewable of the library context's user scale factor which will update itself and invoke all of its change listeners when the user scale factor changes, through methods like setUiScaleFactor(float).
    If you no longer reference a reactive property view strongly in your code, then it will be garbage collected alongside all of its change listeners automatically for you!
    static SwingTree
    get()
    Returns the singleton instance of the SwingTree.
    long
    getDefaultAnimationInterval()
    Returns the default animation interval in milliseconds which is a property that determines the delay between two consecutive animation steps.
    EventProcessor
    getEventProcessor()
    The EventProcessor is a simple interface whose implementations delegate tasks to threads that are capable of processing GUI or application events.
    Map<IconDeclaration,ImageIcon>
    getIconCache()
    The icon cash is a hash map that uses an IconDeclaration as a key and an ImageIcon as a value.
    StyleSheet
    getStyleSheet()
    The StyleSheet is an abstract class whose extensions are used to declare component styles through a CSS like DSL API.
    String
    getSystemInfo()
    Exposes a set of system properties in the form of a nicely formatted string.
    double
    getSystemScaleFactor()
    Returns the system scale factor.
    double
    getSystemScaleFactorOf(Graphics2D g)
    Returns the system scale factor for the given graphics context.
    float
    getUiScaleFactor()
    Returns the user scale factor is a scaling factor is used by SwingTree's style engine to scale the UI during painting.
    static void
    initialiseUsing(SwingTreeConfigurator configurator)
    A lazy initialization of the singleton instance of the SwingTree class causing it to be recreated the next time it is requested through get(),
    but with a SwingTreeConfigurator that is used to configure the SwingTree instance.
    This is useful for testing purposes, but also in cases where the UI scale must be initialized or changed manually (through the reference font).
    Also see initialize().
    static void
    initialize()
    A lazy initialization of the singleton instance of the SwingTree class causing it to be recreated the next time it is requested through get().
    This is useful for testing purposes, also in cases where the UI scale changes (through the reference font).
    Also see initialiseUsing(SwingTreeConfigurator).
    boolean
    isSystemScalingEnabled()
    Returns whether system scaling is enabled.
    boolean
    isUiScaleFactorEnabled()
    Returns whether the UI scaling mode is enabled as is specified by the system property swingtree.uiScale.enabled.
    org.slf4j.Marker
    logMarker()
    Exposes the library wide logging Marker used by SwingTree for all its logging.
    Font
    scale(Font font)
    Applies a custom scale factor given in system property "swingtree.uiScale" to the given font.
    void
    setDefaultAnimationInterval(long defaultAnimationInterval)
    Sets the default animation interval in milliseconds which is a property that determines the delay between two consecutive animation steps.
    void
    setEventProcessor(EventProcessor eventProcessor)
    Sets the EventProcessor that is used to process GUI and application events.
    void
    setStyleSheet(StyleSheet styleSheet)
    Sets the StyleSheet that is used to style components.
    void
    setUiScaleFactor(float scaleFactor)
    Sets the user scale factor is a scaling factor that is used by SwingTree's style engine to scale the UI during painting.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • get

      public static SwingTree get()
      Returns the singleton instance of the SwingTree. Note that this method will create the singleton if it does not exist.
      Returns:
      the singleton instance of the SwingTree.

    • clear

      public static void clear()
      Clears the singleton instance of the SwingTree. This is useful for testing purposes, or if you want to reconfigure your application with a different SwingTreeInitConfig. (see initialiseUsing(SwingTreeConfigurator)).

    • initialize

      public static void initialize()
      A lazy initialization of the singleton instance of the SwingTree class causing it to be recreated the next time it is requested through get().
      This is useful for testing purposes, also in cases where the UI scale changes (through the reference font).
      Also see initialiseUsing(SwingTreeConfigurator).

    • initialiseUsing

      public static void initialiseUsing(SwingTreeConfigurator configurator)
      A lazy initialization of the singleton instance of the SwingTree class causing it to be recreated the next time it is requested through get(),
      but with a SwingTreeConfigurator that is used to configure the SwingTree instance.
      This is useful for testing purposes, but also in cases where the UI scale must be initialized or changed manually (through the reference font).
      Also see initialize().
      Parameters:
      configurator - the SwingTreeConfigurator that is used to configure the SwingTree instance.

    • getIconCache

      public Map<IconDeclaration,ImageIcon> getIconCache()
      The icon cash is a hash map that uses an IconDeclaration as a key and an ImageIcon as a value. This is used to cache icons that are loaded from the file system using convenience methods like UIFactoryMethods.findIcon(String) and UIFactoryMethods.findIcon(IconDeclaration) or UIFactoryMethods.findSvgIcon(String), UIFactoryMethods.findSvgIcon(IconDeclaration).
      Note that the map returned by this method is mutable and can be used to add or remove icons from the cache. You may also want to consider this as a possible source of memory leaks.
      Returns:
      The icon cache of this context, which is used to cache icons that are loaded from the file system.

    • getUiScaleFactor

      public float getUiScaleFactor()
      Returns the user scale factor is a scaling factor is used by SwingTree's style engine to scale the UI during painting. Note that this is different from the system/Graphics2D scale factor, which is the scale factor that the JRE uses to scale everything through the AffineTransform of the Graphics2D.

      Use this scaling factor for painting operations that are not performed by SwingTree's style engine, e.g. custom painting (see ComponentStyleDelegate.painter(UI.Layer, Painter)).

      You can configure this scaling factor through the library initialization method initialiseUsing(SwingTreeConfigurator), or directly through the system property "swingtree.uiScale".

      Returns:
      The user scale factor.

    • setUiScaleFactor

      public void setUiScaleFactor(float scaleFactor)
      Sets the user scale factor is a scaling factor that is used by SwingTree's style engine to scale the UI during painting. Note that this is different from the system/Graphics2D scale factor, which is the scale factor that the JRE uses to scale everything through the AffineTransform of the Graphics2D.

      Use this scaling factor for painting operations that are not performed by SwingTree's style engine, e.g. custom painting (see ComponentStyleDelegate.painter(UI.Layer, Painter)).

      You can configure this scaling factor through the library initialization method initialiseUsing(SwingTreeConfigurator), or directly through the system property "swingtree.uiScale".

      Parameters:
      scaleFactor - The user scale factor.

    • createAndGetUiScaleView

      public sprouts.Viewable<Float> createAndGetUiScaleView()
      Creates and returns a reactive Viewable of the library context's user scale factor which will update itself and invoke all of its change listeners when the user scale factor changes, through methods like setUiScaleFactor(float).
      If you no longer reference a reactive property view strongly in your code, then it will be garbage collected alongside all of its change listeners automatically for you!

      The user scale factor is a scaling factor that is used by SwingTree's style engine to scale the UI during painting.

      Note that this is different from the system/Graphics2D scale factor, which is the scale factor that the JRE uses to scale everything through the AffineTransform of the Graphics2D.

      Use this scaling factor for painting operations that are not performed by SwingTree's style engine, e.g. custom painting (see ComponentStyleDelegate.painter(UI.Layer, Painter)).

      You can configure this scaling factor through the library initialization method initialiseUsing(SwingTreeConfigurator), or directly through the system property "swingtree.uiScale".

      Returns:
      A reactive property holding the current user scale factor used for scaling the UI of your application. You may hold onto such a view and register change listeners on it to ensure your components always have the correct scale!

    • isUiScaleFactorEnabled

      public boolean isUiScaleFactorEnabled()
      Returns whether the UI scaling mode is enabled as is specified by the system property swingtree.uiScale.enabled.

    • scale

      public Font scale(Font font)
      Applies a custom scale factor given in system property "swingtree.uiScale" to the given font.

    • applyScaleAsFontSize

      public Font applyScaleAsFontSize(Font font)
      Converts the current scale factor given in system property "swingtree.uiScale" to a font size and then returns a new font derived from the provided one, with that new size!

    • isSystemScalingEnabled

      public boolean isSystemScalingEnabled()
      Returns whether system scaling is enabled. System scaling means that the JRE scales everything through the AffineTransform of the Graphics2D. If this is the case, then we do not have to do scaled painting and can use the original size of icons, gaps, etc.
      Returns:
      true if system scaling is enabled.

    • getSystemScaleFactorOf

      public double getSystemScaleFactorOf(Graphics2D g)
      Returns the system scale factor for the given graphics context. The system scale factor is the scale factor that the JRE uses to scale everything (text, icons, gaps, etc).
      Parameters:
      g - The graphics context to get the system scale factor for.
      Returns:
      The system scale factor for the given graphics context.

    • getSystemScaleFactor

      public double getSystemScaleFactor()
      Returns the system scale factor. The system scale factor is the scale factor that the JRE uses to scale everything (text, icons, gaps, etc) irrespective of the current look and feel, as this is the scale factor that is used by the AffineTransform of the Graphics2D.
      Returns:
      The system scale factor.

    • getEventProcessor

      public EventProcessor getEventProcessor()
      The EventProcessor is a simple interface whose implementations delegate tasks to threads that are capable of processing GUI or application events. As part of this singleton, the SwingTree library maintains a global EventProcessor that is used consistently by all declarative builders.
      Returns:
      The currently configured EventProcessor that is used to process GUI and application events.

    • setEventProcessor

      public void setEventProcessor(EventProcessor eventProcessor)
      Sets the EventProcessor that is used to process GUI and application events. You may not pass null as an argument, because SwingTree requires an event processor to function.
      Parameters:
      eventProcessor - the EventProcessor that is used to process GUI and application events.
      Throws:
      NullPointerException - if eventProcessor is null!

    • getStyleSheet

      public StyleSheet getStyleSheet()
      The StyleSheet is an abstract class whose extensions are used to declare component styles through a CSS like DSL API. As part of this singleton, the SwingTree library maintains a global StyleSheet that is used consistently by all declarative builders. Use this method to access this global style sheet.
      Returns:
      The currently configured StyleSheet that is used to style components.

    • setStyleSheet

      public void setStyleSheet(StyleSheet styleSheet)
      Sets the StyleSheet that is used to style components. Use StyleSheet.none() instead of null to switch off global styling.
      Parameters:
      styleSheet - The StyleSheet that is used to style components.
      Throws:
      NullPointerException - if styleSheet is null!

    • getDefaultAnimationInterval

      public long getDefaultAnimationInterval()
      Returns the default animation interval in milliseconds which is a property that determines the delay between two consecutive animation steps. You can think of it as the time between the heartbeats of the animation. The smaller the interval, the higher the refresh rate and the smoother the animation will look. However, the smaller the interval, the more CPU time will be used. The default interval is 16 ms which corresponds to almost 60 fps.
      This property is used as default value by the LifeTime object which is used to define the duration of an Animation. The value returned by this is used by animations if no other interval is specified through LifeTime.withInterval(long, TimeUnit).
      Returns:
      The default animation interval in milliseconds.

    • setDefaultAnimationInterval

      public void setDefaultAnimationInterval(long defaultAnimationInterval)
      Sets the default animation interval in milliseconds which is a property that determines the delay between two consecutive animation steps. You can think of it as the time between the heartbeats of the animation. The smaller the interval, the higher the refresh rate and the smoother the animation will look. However, the smaller the interval, the more CPU time will be used. The default interval is 16 ms which corresponds to almost 60 fps.
      This property is used as default value by the LifeTime object which is used to define the duration of an Animation. The value returned by this is used by animations if no other interval is specified through LifeTime.withInterval(long, TimeUnit).
      Parameters:
      defaultAnimationInterval - The default animation interval in milliseconds.

    • getSystemInfo

      public String getSystemInfo()
      Exposes a set of system properties in the form of a nicely formatted string. These are used by the SwingTree library to determine the system configuration and to adjust the UI accordingly.
      Returns:
      A string containing system information.

    • logMarker

      public org.slf4j.Marker logMarker()
      Exposes the library wide logging Marker used by SwingTree for all its logging. You may use this marker to channel SwingTree logs to a separate log file or to filter them in any other way you like.
      To configure the logging Marker, check out the initialiseUsing(SwingTreeConfigurator) method, where you may provide a custom SwingTreeConfigurator that sets the logging Marker through the SwingTreeInitConfig.
      Returns:
      The logging Marker which is passed to methods of the SLF4J logger.