SwingTreeInitConfig.java

  1. package swingtree;

  3. import org.jspecify.annotations.Nullable;
  4. import swingtree.style.StyleSheet;
  5. import swingtree.threading.EventProcessor;

  7. import java.awt.Font;
  8. import java.util.Objects;
  9. import java.util.Optional;
  10. import java.util.function.Supplier;

  12. /**
  13.  *  An immutable configuration object for the {@link SwingTree} library,
  14.  *  which can be configured using a functional {@link SwingTreeConfigurator} lambda
  15.  *  passed to {@link SwingTree#initialiseUsing(SwingTreeConfigurator)}.
  16.  *  <p>
  17.  *  It allows for the configuration of the default
  18.  *  font, font installation, scaling, event processing and
  19.  *  application wide {@link StyleSheet}.
  20.  */
  21. public final class SwingTreeInitConfig
  22. {
  23.     /**
  24.      *  Defines how the {@link Font}, specified through {@link SwingTreeInitConfig#defaultFont(Font)},
  25.      *  is installed in the {@link javax.swing.UIManager}.
  26.      */
  27.     public enum FontInstallation
  28.     {
  29.         /**
  30.          *  A soft installation will only install the font as the "defaultFont" property
  31.          *  of the {@link javax.swing.UIManager}.
  32.          */
  33.         SOFT,

  35.         /**
  36.          *  A hard installation will install the font as the "defaultFont" property
  37.          *  of the {@link javax.swing.UIManager} and as the default font of all
  38.          *  {@link javax.swing.UIManager} components.
  39.          */
  40.         HARD,

  42.         /**
  43.          *  No installation will be performed.
  44.          */
  45.         NONE
  46.     }

  48.     /**
  49.      *  Defines how the scaling factor for the UI should be determined.
  50.      */
  51.     public enum Scaling
  52.     {
  53.         /**
  54.          *  No scaling will be performed.
  55.          */
  56.         NONE,

  58.         /**
  59.          *  The scaling will be derived from the supplied scaling factor.
  60.          *  (see {@link SwingTreeInitConfig#uiScaleFactor(float)} as well as
  61.          *  system property {@code "swingtree.uiScale"}).
  62.          */
  63.         FROM_SCALING_FACTOR,

  65.         /**
  66.          *  The scaling will be derived from the default font size,
  67.          *  if a default font was specified. (see {@link SwingTreeInitConfig#defaultFont(Font)})
  68.          */
  69.         FROM_DEFAULT_FONT,

  71.         /**
  72.          *  The scaling will be derived from the system font size.
  73.          *  This scaling policy is chosen if no default font was specified,
  74.          *  no scaling factor was specified and the scaling mode is enabled
  75.          *  (see {@link SwingTreeInitConfig#isUiScaleFactorEnabled()}).
  76.          */
  77.         FROM_SYSTEM_FONT
  78.     }

  80.     public static SwingTreeInitConfig standard() {
  81.         return new SwingTreeInitConfig(
  82.                         null,
  83.                         FontInstallation.SOFT,
  84.                         EventProcessor.COUPLED_STRICT,
  85.                         StyleSheet.none(),
  86.                         SystemProperties.getFloat(SystemProperties.UI_SCALE,                 -1    ),
  87.                         SystemProperties.getBool(SystemProperties.UI_SCALE_ENABLED,          true  ),
  88.                         SystemProperties.getBool(SystemProperties.UI_SCALE_ALLOW_SCALE_DOWN, false ),
  89.                         SystemProperties.getLong(SystemProperties.ANIMATION_INTERVAL,        16    )
  90.                     );
  91.                     /*
  92.                         Note that we want the refresh rate to be as high as possible so that the animation
  93.                         looks smooth, but we don't want to use 100% of the CPU.
  94.                         The ideal refresh rate is 60 fps which is 16.6 ms per frame.
  95.                         So we set the timer to 16 ms.
  96.                         This does of course not account for the time it takes to run the animation
  97.                         code, but that should be negligible, and in the worst case
  98.                         the animation will be a bit slower than 60 fps.
  99.                     */
  100.     }


  103.     private final @Nullable Font   _defaultFont; // may be null
  104.     private final FontInstallation _fontInstallation;
  105.     private final EventProcessor   _eventProcessor;
  106.     private final StyleSheet       _styleSheet;
  107.     private final float            _uiScale;
  108.     private final boolean          _uiScaleEnabled;
  109.     private final boolean          _uiScaleAllowScaleDown;
  110.     private final long             _defaultAnimationInterval;


  113.     private SwingTreeInitConfig(
  114.         @Nullable Font   defaultFont,
  115.         FontInstallation fontInstallation,
  116.         EventProcessor   eventProcessor,
  117.         StyleSheet       styleSheet,
  118.         float            uiScale,
  119.         boolean          uiScaleEnabled,
  120.         boolean          uiScaleAllowScaleDown,
  121.         long             defaultAnimationInterval
  122.     ) {
  123.         _defaultFont              = defaultFont;
  124.         _fontInstallation         = Objects.requireNonNull(fontInstallation);
  125.         _eventProcessor           = Objects.requireNonNull(eventProcessor);
  126.         _styleSheet               = Objects.requireNonNull(styleSheet);
  127.         _uiScale                  = uiScale;
  128.         _uiScaleEnabled           = uiScaleEnabled;
  129.         _uiScaleAllowScaleDown    = uiScaleAllowScaleDown;
  130.         _defaultAnimationInterval = defaultAnimationInterval;
  131.     }

  133.     /**
  134.      *  Returns an {@link Optional} containing the default font
  135.      *  or an empty {@link Optional} if no default font is set.
  136.      */
  137.     Optional<Font> defaultFont() {
  138.         return Optional.ofNullable(_defaultFont);
  139.     }

  141.     /**
  142.      *  Returns the {@link FontInstallation} mode.
  143.      */
  144.     FontInstallation fontInstallation() {
  145.         return _fontInstallation;
  146.     }

  148.     /**
  149.      *  Returns the {@link Scaling} mode
  150.      *  which is determined based on the configuration.
  151.      *  <ul>
  152.      *      <li>
  153.      *          If {@code false} was passed to {@link #isUiScaleFactorEnabled(boolean)},
  154.      *          then {@link Scaling#NONE} is returned.
  155.      *      </li>
  156.      *      <li>
  157.      *          Otherwise, if a scaling factor greater than 0 was passed to {@link #uiScaleFactor(float)},
  158.      *          then {@link Scaling#FROM_SCALING_FACTOR} is returned.
  159.      *      </li>
  160.      *      <li>
  161.      *          Otherwise, if a default font was passed to {@link #defaultFont(Font)}, <br>
  162.      *          then {@link Scaling#FROM_DEFAULT_FONT} is returned. <br>
  163.      *      </li>
  164.      *  </ul>
  165.      *  <p>
  166.      *  If none of the above applies, then {@link Scaling#FROM_SYSTEM_FONT} is returned. <br>
  167.      */
  168.     Scaling scalingStrategy() {
  169.         if ( !_uiScaleEnabled )
  170.             return Scaling.NONE;
  171.         if ( _uiScale > 0 )
  172.             return Scaling.FROM_SCALING_FACTOR;
  173.         if ( _defaultFont != null )
  174.             return Scaling.FROM_DEFAULT_FONT;

  176.         return Scaling.FROM_SYSTEM_FONT;
  177.     }

  179.     /**
  180.      *  Returns the {@link EventProcessor},
  181.      *  which is used to process both UI and application events.
  182.      */
  183.     EventProcessor eventProcessor() {
  184.         return _eventProcessor;
  185.     }

  187.     /**
  188.      *  Returns an {@link Optional} containing the {@link StyleSheet}
  189.      *  or an empty {@link Optional} if no {@link StyleSheet} is set.
  190.      */
  191.     StyleSheet styleSheet() {
  192.         return _styleSheet;
  193.     }

  195.     /**
  196.      *  Returns the UI scaling factor as is specified by the system property {@code swingtree.uiScale}.
  197.      */
  198.     float uiScaleFactor() {
  199.         return _uiScale;
  200.     }

  202.     /**
  203.      *  Returns whether the UI scaling mode is enabled as is specified by the system property {@code swingtree.uiScale.enabled}.
  204.      */
  205.     boolean isUiScaleFactorEnabled() {
  206.         return _uiScaleEnabled;
  207.     }

  209.     /**
  210.      *  Returns whether values smaller than 100% are allowed for the user scale factor
  211.      *  as is specified by the system property {@code swingtree.uiScale.allowScaleDown}.
  212.      */
  213.     boolean isUiScaleDownAllowed() {
  214.         return _uiScaleAllowScaleDown;
  215.     }

  217.     /**
  218.      *  Returns the default animation interval in milliseconds,
  219.      *  which is a property that
  220.      *  determines the delay between two consecutive animation steps.
  221.      *  You can think of it as the time between the heartbeats of the animation.
  222.      *  The smaller the interval, the higher the refresh rate and
  223.      *  the smoother the animation will look.
  224.      *  However, the smaller the interval, the more CPU time will be used.
  225.      *  The default interval is 16 ms which corresponds to 60 fps.
  226.      *  See {@link #standard()}, returning an instance of this config with the default value. <br>
  227.      *  This property is used as default value by the {@link swingtree.animation.LifeTime}
  228.      *  object which is used to define the duration of an {@link swingtree.animation.Animation}.
  229.      */
  230.     long defaultAnimationInterval() {
  231.         return _defaultAnimationInterval;
  232.     }

  234.     /**
  235.      *  Used to configure the default font, which may be used by the {@link SwingTree}
  236.      *  to derive the UI scaling factor and or to install the font in the {@link javax.swing.UIManager}
  237.      *  depending on the {@link FontInstallation} mode (see {@link #defaultFont(Font, FontInstallation)}).
  238.      * @param newDefaultFont The new default font, or {@code null} to unset the default font.
  239.      * @return A new {@link SwingTreeInitConfig} instance with the new default font.
  240.      */
  241.     public SwingTreeInitConfig defaultFont( Font newDefaultFont ) {
  242.         return new SwingTreeInitConfig(newDefaultFont, _fontInstallation, _eventProcessor, _styleSheet, _uiScale, _uiScaleEnabled, _uiScaleAllowScaleDown, _defaultAnimationInterval);
  243.     }

  245.     /**
  246.      *  Used to configure both the default {@link Font} and the {@link FontInstallation} mode.
  247.      *  <p>
  248.      *  The {@link FontInstallation} mode determines how the {@link Font} is installed
  249.      *  in the {@link javax.swing.UIManager} (see {@link FontInstallation}).
  250.      *  <p>
  251.      *  If the {@link FontInstallation} mode is {@link FontInstallation#SOFT},
  252.      *  then the {@link Font} will only be installed as the "defaultFont" property
  253.      *  in the {@link javax.swing.UIManager}. If on the other hand the {@link FontInstallation}
  254.      *  mode is {@link FontInstallation#HARD}, then the {@link Font} will be installed
  255.      *  by replacing all {@link Font}s in the {@link javax.swing.UIManager}.
  256.      *
  257.      * @param newDefaultFont The new default font, or {@code null} to unset the default font.
  258.      * @param newFontInstallation The new {@link FontInstallation} mode.
  259.      * @return A new {@link SwingTreeInitConfig} instance with the new default font and {@link FontInstallation} mode.
  260.      */
  261.     public SwingTreeInitConfig defaultFont( Font newDefaultFont, FontInstallation newFontInstallation ) {
  262.         return new SwingTreeInitConfig(newDefaultFont, newFontInstallation, _eventProcessor, _styleSheet, _uiScale, _uiScaleEnabled, _uiScaleAllowScaleDown, _defaultAnimationInterval);
  263.     }

  265.     /**
  266.      *  Used to configure the {@link EventProcessor}, which is used to process both
  267.      *  UI and application events.
  268.      *  You may create your own {@link EventProcessor} implementation or use one of the
  269.      *  predefined ones like {@link EventProcessor#COUPLED_STRICT}, {@link EventProcessor#COUPLED}
  270.      *  or {@link EventProcessor#DECOUPLED}.
  271.      *
  272.      * @param newEventProcessor The new {@link EventProcessor}.
  273.      * @return A new {@link SwingTreeInitConfig} instance with the new {@link EventProcessor}.
  274.      */
  275.     public SwingTreeInitConfig eventProcessor( EventProcessor newEventProcessor ) {
  276.         return new SwingTreeInitConfig(_defaultFont, _fontInstallation, newEventProcessor, _styleSheet, _uiScale, _uiScaleEnabled, _uiScaleAllowScaleDown, _defaultAnimationInterval);
  277.     }

  279.     /**
  280.      *  Used to configure a global {@link StyleSheet} serving as a base for all
  281.      *  {@link StyleSheet}s used inside your application (see {@link UI#use(swingtree.style.StyleSheet, Supplier)}).
  282.      *
  283.      * @param newStyleSheet The new {@link StyleSheet}, or {@code null} to unset the {@link StyleSheet}.
  284.      * @return A new {@link SwingTreeInitConfig} instance with the new {@link StyleSheet}.
  285.      */
  286.     public SwingTreeInitConfig styleSheet( StyleSheet newStyleSheet ) {
  287.         return new SwingTreeInitConfig(_defaultFont, _fontInstallation, _eventProcessor, newStyleSheet, _uiScale, _uiScaleEnabled, _uiScaleAllowScaleDown, _defaultAnimationInterval);
  288.     }

  290.     /**
  291.      *  Use this to configure the UI scaling factor.
  292.      *  The default factor determined by the system property {@code "swingtree.uiScale"}.
  293.      *  <p>
  294.      *  If Java runtime scales (Java 9 or later), this scale factor is applied on top
  295.      *  of the Java system scale factor. Java 8 does not scale and this scale factor
  296.      *  replaces the user scale factor that SwingTree computes based on the font.
  297.      *  To replace the Java 9+ system scale factor, use system property "sun.java2d.uiScale",
  298.      *  which has the same syntax as this one.
  299.      *  <p>
  300.      *  <strong>Allowed Values</strong> e.g. {@code 1.5}, {@code 1.5x}, {@code 150%} or {@code 144dpi} (96dpi is 100%)<br>
  301.      *
  302.      * @param newUiScale The new UI scaling factor.
  303.      * @return A new {@link SwingTreeInitConfig} instance with the new UI scaling factor.
  304.      */
  305.     public SwingTreeInitConfig uiScaleFactor( float newUiScale ) {
  306.         return new SwingTreeInitConfig(_defaultFont, _fontInstallation, _eventProcessor, _styleSheet, newUiScale, _uiScaleEnabled, _uiScaleAllowScaleDown, _defaultAnimationInterval);
  307.     }

  309.     /**
  310.      *  Used to configure whether the UI scaling mode is enabled as is specified by the
  311.      *  system property {@code swingtree.uiScale.enabled}.
  312.      *  <p>
  313.      *  <strong>Allowed Values</strong> {@code false} and {@code true}<br>
  314.      *  <strong>Default</strong> {@code true}
  315.      *
  316.      * @param newUiScaleEnabled The new UI scaling mode.
  317.      * @return A new {@link SwingTreeInitConfig} instance with the new UI scaling mode.
  318.      */
  319.     public SwingTreeInitConfig isUiScaleFactorEnabled( boolean newUiScaleEnabled ) {
  320.         return new SwingTreeInitConfig(_defaultFont, _fontInstallation, _eventProcessor, _styleSheet, _uiScale, newUiScaleEnabled, _uiScaleAllowScaleDown, _defaultAnimationInterval);
  321.     }

  323.     /**
  324.      *  Used to configure whether values smaller than 100% are allowed for the user scale factor
  325.      *  as is specified by the system property {@code swingtree.uiScale.allowScaleDown}.
  326.      *  <p>
  327.      *  <strong>Allowed Values</strong> {@code false} and {@code true}<br>
  328.      *  <strong>Default</strong> {@code false}
  329.      *
  330.      * @param newUiScaleAllowScaleDown The new UI scaling mode.
  331.      * @return A new {@link SwingTreeInitConfig} instance with the new UI scaling mode.
  332.      */
  333.     public SwingTreeInitConfig isUiScaleDownAllowed( boolean newUiScaleAllowScaleDown ) {
  334.         return new SwingTreeInitConfig(_defaultFont, _fontInstallation, _eventProcessor, _styleSheet, _uiScale, _uiScaleEnabled, newUiScaleAllowScaleDown, _defaultAnimationInterval);
  335.     }

  337.     /**
  338.      *  Used to configure the default animation interval in milliseconds,
  339.      *  which is a property that
  340.      *  determines the delay between two consecutive animation steps.
  341.      *  You can think of it as the time between the heartbeats of the animation.
  342.      *  The smaller the interval, the higher the refresh rate and
  343.      *  the smoother the animation will look.
  344.      *  However, the smaller the interval, the more CPU time will be used.
  345.      *  The default interval is 16 ms which corresponds to 60 fps.
  346.      *  See {@link #standard()}, returning an instance of this config with the default value. <br>
  347.      *  This property is used as default value by the {@link swingtree.animation.LifeTime}
  348.      *  object which is used to define the duration of an {@link swingtree.animation.Animation}.
  349.      *
  350.      * @param newDefaultAnimationInterval The new default animation interval.
  351.      * @return A new {@link SwingTreeInitConfig} instance with the new default animation interval.
  352.      */
  353.     public SwingTreeInitConfig defaultAnimationInterval( long newDefaultAnimationInterval ) {
  354.         return new SwingTreeInitConfig(_defaultFont, _fontInstallation, _eventProcessor, _styleSheet, _uiScale, _uiScaleEnabled, _uiScaleAllowScaleDown, newDefaultAnimationInterval);
  355.     }

  357.     /**
  358.      * Defines/documents own system properties used in SwingTree.
  359.      *
  360.      * @author Daniel Nepp, but originally a derivative work of Karl Tauber
  361.      */
  362.     private static interface SystemProperties
  363.     {
  364.         /**
  365.          * Specifies a custom scale factor used to scale the UI.
  366.          * <p>
  367.          * If Java runtime scales (Java 9 or later), this scale factor is applied on top
  368.          * of the Java system scale factor. Java 8 does not scale and this scale factor
  369.          * replaces the user scale factor that SwingTree computes based on the font.
  370.          * To replace the Java 9+ system scale factor, use system property "sun.java2d.uiScale",
  371.          * which has the same syntax as this one.
  372.          * <p>
  373.          * <strong>Allowed Values</strong> e.g. {@code 1.5}, {@code 1.5x}, {@code 150%} or {@code 144dpi} (96dpi is 100%)<br>
  374.          */
  375.         String UI_SCALE = "swingtree.uiScale";

  377.         /**
  378.          * Specifies whether user scaling mode is enabled.
  379.          * <p>
  380.          * <strong>Allowed Values</strong> {@code false} and {@code true}<br>
  381.          * <strong>Default</strong> {@code true}
  382.          */
  383.         String UI_SCALE_ENABLED = "swingtree.uiScale.enabled";

  385.         /**
  386.          * Specifies whether values smaller than 100% are allowed for the user scale factor
  387.          * (see {@link UI#scale()}).
  388.          * <p>
  389.          * <strong>Allowed Values</strong> {@code false} and {@code true}<br>
  390.          * <strong>Default</strong> {@code false}
  391.          */
  392.         String UI_SCALE_ALLOW_SCALE_DOWN = "swingtree.uiScale.allowScaleDown";

  394.         /**
  395.          * Specifies the default animation interval in milliseconds.
  396.          * <p>
  397.          * This property is used as default value by the {@link swingtree.animation.LifeTime}
  398.          * object which is used to define the duration of an {@link swingtree.animation.Animation}.
  399.          * <p>
  400.          * <strong>Allowed Values</strong> must be a positive integer<br>
  401.          * <strong>Default</strong> {@code 16}
  402.          */
  403.         String ANIMATION_INTERVAL = "swingtree.animationInterval";

  405.         /**
  406.          * Checks whether a system property is set and returns {@code true} if its value
  407.          * is {@code "true"} (case-insensitive), otherwise it returns {@code false}.
  408.          * If the system property is not set, {@code defaultValue} is returned.
  409.          */
  410.         static boolean getBool( String key, boolean defaultValue ) {
  411.             String value = System.getProperty( key );
  412.             return (value != null) ? Boolean.parseBoolean( value ) : defaultValue;
  413.         }

  415.         /**
  416.          * Similar to sun.java2d.SunGraphicsEnvironment.getScaleFactor(String)
  417.          */
  418.         static float getFloat( String key, float defaultValue ) {
  419.             String s = System.getProperty( key );

  421.             if ( s == null )
  422.                 return defaultValue;

  424.             float units = 1;
  425.             if ( s.endsWith( "x" ) )
  426.                 s = s.substring( 0, s.length() - 1 );
  427.             else if ( s.endsWith( "dpi" ) ) {
  428.                 units = 96;
  429.                 s = s.substring( 0, s.length() - 3 );
  430.             } else if ( s.endsWith( "%" ) ) {
  431.                 units = 100;
  432.                 s = s.substring( 0, s.length() - 1 );
  433.             }

  435.             try {
  436.                 float scale = Float.parseFloat( s );
  437.                 return scale > 0 ? scale / units : -1;
  438.             } catch( NumberFormatException ex ) {
  439.                 return defaultValue;
  440.             }
  441.         }

  443.         static long getLong( String key, long defaultValue ) {
  444.             String s = System.getProperty( key );

  446.             if ( s == null )
  447.                 return defaultValue;

  449.             try {
  450.                 long interval = Long.parseLong( s );
  451.                 return interval > 0 ? interval : defaultValue;
  452.             } catch( NumberFormatException ex ) {
  453.                 return defaultValue;
  454.             }
  455.         }
  456.     }
  457. }
Created with JaCoCo 0.8.11.202310140853