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.
    static SwingTree
    get()
    Returns the singleton instance of the SwingTree.
    sprouts.Viewable<AWTEvent>
    getAwtEventView(long mask)
    This method constitutes a memory safe alternative to Toolkit.addAWTEventListener(AWTEventListener, long) as it returns a weakly referenced reactive property that will automatically be garbage collected alongside its change listeners when you no longer reference it strongly in your code.
    You use the reactive Viewable returned by this method to register change listeners that will be invoked whenever an AWT event matching the given mask is fired anywhere in the application.
    The supplied eventMask is a bitmask of event types to receive.
    long
    getDefaultAnimationInterval()
    Returns the default animation interval in milliseconds which is a property that determines the delay between two consecutive animation steps.
    String
    getDevToolKeyStrokeShortcut()
    Returns the keystroke shortcut that is used to toggle the SwingTree dev-tool, which is a classical inspector tool that creates an overlay on top of the UI and shows debug information about the component under the mouse cursor.
    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 cache 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()
    There are two types of strategies for achieving high DPI scaling in Swing.
    sprouts.Viewable<Float>
    getUiScaleView()
    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 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 initializeUsing(SwingTreeConfigurator).
    static void
    initializeUsing(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().
    boolean
    isDevToolEnabled()
    Returns whether the SwingTree dev-tool is currently enabled or not.
    sprouts.Viewable<Boolean>
    isDevToolEnabledView()
    Creates and returns a reactive Viewable of the library context's dev-tool enabled state which will update itself and invoke all of its change listeners when the dev-tool enabled state changes, through methods like setDevToolEnabled(boolean) or through the keystroke shortcut returned by getDevToolKeyStrokeShortcut().
    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 dev-tool is a classical inspector tool that creates an overlay on top of the UI and shows debug information about the component under the mouse cursor.
    boolean
    isRecordingDebugSourceTrace()
    Returns whether the library is configured to record debug source traces for components during their creation.
    If this is the case, then SwingTree will record the stack trace of a component at the moment of its creation.
    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
    setDevToolEnabled(boolean enabled)
    Enables or disables the SwingTree dev-tool, which is a classical inspector tool that creates an overlay on top of the UI and summons an additional dialog showing debug information about the component under the mouse cursor.
    You can also toggle it through the keystroke shortcut returned by getDevToolKeyStrokeShortcut(), which is "ctrl shift I" by default.
    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 initializeUsing(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 initializeUsing(SwingTreeConfigurator).

    • initializeUsing

      public static void initializeUsing(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.

    • getAwtEventView

      public sprouts.Viewable<AWTEvent> getAwtEventView(long mask)
      This method constitutes a memory safe alternative to Toolkit.addAWTEventListener(AWTEventListener, long) as it returns a weakly referenced reactive property that will automatically be garbage collected alongside its change listeners when you no longer reference it strongly in your code.
      You use the reactive Viewable returned by this method to register change listeners that will be invoked whenever an AWT event matching the given mask is fired anywhere in the application.
      The supplied eventMask is a bitmask of event types to receive. It is constructed by bitwise OR-ing together the event masks defined in AWTEvent.
      There are many event ids, like MouseEvent.BUTTON1, MouseEvent.MOUSE_CLICKED, KeyEvent.KEY_PRESSED, ComponentEvent.COMPONENT_MOVED, ComponentEvent.COMPONENT_MOVED, etc...

      Note that when the SwingTree library context gets cleared through clear() or replaced through initialize() or initializeUsing(SwingTreeConfigurator), then the reactive view returned by this method will no longer receive updates and will be effectively dead!

      Parameters:
      mask - the bitmask of event types to receive, constructed by bitwise OR-ing together the event masks defined in AWTEvent. For example, if you want to listen to mouse clicks and key presses, you would pass in AWTEvent.MOUSE_EVENT_MASK | AWTEvent.KEY_EVENT_MASK as the mask.
      Returns:
      a reactive Viewable that will update itself and invoke all of its change listeners whenever an AWT event matching the given mask is fired anywhere in the application.
      See Also:

    • isRecordingDebugSourceTrace

      public boolean isRecordingDebugSourceTrace()
      Returns whether the library is configured to record debug source traces for components during their creation.
      If this is the case, then SwingTree will record the stack trace of a component at the moment of its creation. It will be captured as a Tuple of StackTraceElements and then stored as a client properties under the "built-at" key.
      This source location trace is primarily used by the SwingTree dev-tool, which can be enabled through pressing the getDevToolKeyStrokeShortcut() keystroke shortcut. It creates an overlay on top of the UI that shows debug information about the component under the mouse cursor. When pressing control together with a left click on a component, it opens a dialog showing a lot of important debug information about the component, including the source code location trace.
      Returns:
      true if the library is configured to record debug source traces for components during their creation, false otherwise.
      See Also:

    • getDevToolKeyStrokeShortcut

      public String getDevToolKeyStrokeShortcut()
      Returns the keystroke shortcut that is used to toggle the SwingTree dev-tool, which is a classical inspector tool that creates an overlay on top of the UI and shows debug information about the component under the mouse cursor. By default, the shortcut to enable it is "ctrl shift I", but you can configure it through the SwingTreeInitConfig.devToolKeyStrokeShortcut(String) method of the SwingTreeInitConfig class, which is used to configure the SwingTree instance through the SwingTreeConfigurator in initializeUsing(SwingTreeConfigurator).
      Returns:
      The keystroke shortcut that is used to toggle the SwingTree dev-tool / inspection-tool.
      See Also:

    • isDevToolEnabled

      public boolean isDevToolEnabled()
      Returns whether the SwingTree dev-tool is currently enabled or not. The dev-tool is a classical inspector tool that creates an overlay on top of the UI and shows debug information about the component under the mouse cursor. You can toggle it through the keystroke shortcut returned by getDevToolKeyStrokeShortcut().
      Returns:
      true if the SwingTree dev-tool is currently enabled, false otherwise.
      See Also:

    • setDevToolEnabled

      public void setDevToolEnabled(boolean enabled)
      Enables or disables the SwingTree dev-tool, which is a classical inspector tool that creates an overlay on top of the UI and summons an additional dialog showing debug information about the component under the mouse cursor.
      You can also toggle it through the keystroke shortcut returned by getDevToolKeyStrokeShortcut(), which is "ctrl shift I" by default.
      This method is useful when you want to enable or disable the dev-tool programmatically, for example through a button in your UI, or through a command in your application's console.
      Parameters:
      enabled - true to enable the SwingTree dev-tool, false to disable it.
      See Also:

    • isDevToolEnabledView

      public sprouts.Viewable<Boolean> isDevToolEnabledView()
      Creates and returns a reactive Viewable of the library context's dev-tool enabled state which will update itself and invoke all of its change listeners when the dev-tool enabled state changes, through methods like setDevToolEnabled(boolean) or through the keystroke shortcut returned by getDevToolKeyStrokeShortcut().
      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 dev-tool is a classical inspector tool that creates an overlay on top of the UI and shows debug information about the component under the mouse cursor. You can toggle it through the keystroke shortcut returned by getDevToolKeyStrokeShortcut(), which is "ctrl shift I" by default.
      Returns:
      A reactive property holding whether the SwingTree dev-tool is currently enabled or not. You may hold onto such a view and register change listeners on it to ensure your components always know whether the dev-tool is enabled or not!
      See Also:

    • getIconCache

      public Map<IconDeclaration,ImageIcon> getIconCache()
      The icon cache 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()
      There are two types of strategies for achieving high DPI scaling in Swing. The first one is available since Java 9, and it uses the system property sun.java2d.uiScale to scale the AffineTransform of the Graphics2D graphics context. The second one is look and feel / client code dependent scaling, which is what SwingTree uses in, for example, the style engine or when seting the size of component through the SwingTree API...

      The float based scaling factor returned by this method can be used as a multiplier in order to scale something from "developer pixels" to "component pixels" / "look and feel pixels". Conversely, by dividing a number using this factor, you convert something from "component pixels" to platform-agnostic "developer pixel".
      The scaling factor is computed by SwingTree automatically based on the system font. Anything you do through the SwingTree API, will be scaled for you,
      but if you write code against raw Swing, you may need to use this scale factor to ensure consistent scaling support across screens with varying DPI. Most commonly, you will need to do manual scaling when defining component dimensions or to scale custom Graphics2D based painting operations.
      You can configure this scaling factor through the library initialization method initializeUsing(SwingTreeConfigurator), or directly through the system property "swingtree.uiScale".
      You may also set it using setUiScaleFactor(float).

      Returns:
      The user scale factor to convert between "developer pixel size" and "component pixel size".

    • 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.

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

      Parameters:
      scaleFactor - The user scale factor.

    • getUiScaleView

      public sprouts.Viewable<Float> getUiScaleView()
      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 converts "developer pixel sizes" to "component pixel sizes" and it is used by SwingTree's API to support dynamic DPI scaling.

      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.

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

      Also note that when the SwingTree library context gets cleared through clear() or replaced through initialize() or initializeUsing(SwingTreeConfigurator), then the reactive view returned by this method will no longer receive updates and will be effectively dead!

      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 initializeUsing(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.