From fdf28fc385bf6fd2ae481ddd790bcf2e07d330bf Mon Sep 17 00:00:00 2001 From: Karl Tauber Date: Sat, 23 Jan 2021 18:05:46 +0100 Subject: [PATCH] javadoc and comment updates/fixes --- .../formdev/flatlaf/FlatClientProperties.java | 8 ++- .../com/formdev/flatlaf/UIDefaultsLoader.java | 2 +- .../com/formdev/flatlaf/util/HiDPIUtils.java | 2 +- .../com/formdev/flatlaf/util/UIScale.java | 60 +++++++++++++++++-- .../extras/components/FlatTabbedPane.java | 10 +++- 5 files changed, 73 insertions(+), 9 deletions(-) diff --git a/flatlaf-core/src/main/java/com/formdev/flatlaf/FlatClientProperties.java b/flatlaf-core/src/main/java/com/formdev/flatlaf/FlatClientProperties.java index 470f70c2..c71c0c6a 100644 --- a/flatlaf-core/src/main/java/com/formdev/flatlaf/FlatClientProperties.java +++ b/flatlaf-core/src/main/java/com/formdev/flatlaf/FlatClientProperties.java @@ -22,6 +22,8 @@ import javax.swing.JComponent; import javax.swing.SwingConstants; /** + * Defines/documents own client properties used in FlatLaf. + * * @author Karl Tauber */ public interface FlatClientProperties @@ -293,10 +295,12 @@ public interface FlatClientProperties String TABBED_PANE_MAXIMUM_TAB_WIDTH = "JTabbedPane.maximumTabWidth"; /** - * Specifies the height of a tab. + * Specifies the minimum height of a tab. *

* Component {@link javax.swing.JTabbedPane}
* Value type {@link java.lang.Integer} + * + * @see #TABBED_PANE_TAB_INSETS */ String TABBED_PANE_TAB_HEIGHT = "JTabbedPane.tabHeight"; @@ -306,6 +310,8 @@ public interface FlatClientProperties * Component {@link javax.swing.JTabbedPane} * or tab content components (see {@link javax.swing.JTabbedPane#setComponentAt(int, java.awt.Component)})
* Value type {@link java.awt.Insets} + * + * @see #TABBED_PANE_TAB_HEIGHT */ String TABBED_PANE_TAB_INSETS = "JTabbedPane.tabInsets"; diff --git a/flatlaf-core/src/main/java/com/formdev/flatlaf/UIDefaultsLoader.java b/flatlaf-core/src/main/java/com/formdev/flatlaf/UIDefaultsLoader.java index 3bbf239a..41b6ab89 100644 --- a/flatlaf-core/src/main/java/com/formdev/flatlaf/UIDefaultsLoader.java +++ b/flatlaf-core/src/main/java/com/formdev/flatlaf/UIDefaultsLoader.java @@ -119,7 +119,7 @@ class UIDefaultsLoader addonClassLoaders.add( addonClassLoader ); } - // load custom properties files (usually provides by applications) + // load custom properties files (usually provided by applications) List customDefaultsSources = FlatLaf.getCustomDefaultsSources(); int size = (customDefaultsSources != null) ? customDefaultsSources.size() : 0; for( int i = 0; i < size; i++ ) { diff --git a/flatlaf-core/src/main/java/com/formdev/flatlaf/util/HiDPIUtils.java b/flatlaf-core/src/main/java/com/formdev/flatlaf/util/HiDPIUtils.java index 9fb064b8..6a67af16 100644 --- a/flatlaf-core/src/main/java/com/formdev/flatlaf/util/HiDPIUtils.java +++ b/flatlaf-core/src/main/java/com/formdev/flatlaf/util/HiDPIUtils.java @@ -134,7 +134,7 @@ public class HiDPIUtils // - fractional scale factors result in fractional component Y device coordinates // - fractional text Y device coordinates are rounded for horizontal lines of characters // - maybe different rounding methods for drawing primitives (e.g. rectangle) and text - // - Java adds 0.5 to X/Y positions in before drawing string in BufferedTextPipe.enqueueGlyphList() + // - Java adds 0.5 to X/Y positions before drawing string in BufferedTextPipe.enqueueGlyphList() // this is not the optimal solution, but works very good in most cases // (tested with class FlatPaintingStringTest on Windows 10 with font "Segoe UI") diff --git a/flatlaf-core/src/main/java/com/formdev/flatlaf/util/UIScale.java b/flatlaf-core/src/main/java/com/formdev/flatlaf/util/UIScale.java index 77ee291d..d2e9c269 100644 --- a/flatlaf-core/src/main/java/com/formdev/flatlaf/util/UIScale.java +++ b/flatlaf-core/src/main/java/com/formdev/flatlaf/util/UIScale.java @@ -36,9 +36,14 @@ import javax.swing.plaf.UIResource; import com.formdev.flatlaf.FlatSystemProperties; /** - * Two scaling modes are supported for HiDPI displays: + * This class handles scaling in Swing UIs. + * It computes user scaling factor based on font size and + * provides methods to scale integer, float, {@link Dimension} and {@link Insets}. + * This class is look and feel independent. + *

+ * Two scaling modes are supported by FlatLaf for HiDPI displays: * - * 1) system scaling mode + *

1) system scaling mode

* * This mode is supported since Java 9 on all platforms and in some Java 8 VMs * (e.g. Apple and JetBrains). The JRE determines the scale factor per-display and @@ -49,7 +54,7 @@ import com.formdev.flatlaf.FlatSystemProperties; * The scale factor may be different for each connected display. * The scale factor may change for a window when moving the window from one display to another one. * - * 2) user scaling mode + *

2) user scaling mode

* * This mode is mainly for Java 8 compatibility, but is also used on Linux * or if the default font is changed. @@ -85,6 +90,9 @@ public class UIScale private static Boolean jreHiDPI; + /** + * Returns whether system scaling is enabled. + */ public static boolean isSystemScalingEnabled() { if( jreHiDPI != null ) return jreHiDPI; @@ -112,10 +120,16 @@ public class UIScale return jreHiDPI; } + /** + * Returns the system scale factor for the given graphics context. + */ public static double getSystemScaleFactor( Graphics2D g ) { return isSystemScalingEnabled() ? getSystemScaleFactor( g.getDeviceConfiguration() ) : 1; } + /** + * Returns the system scale factor for the given graphics configuration. + */ public static double getSystemScaleFactor( GraphicsConfiguration gc ) { return (isSystemScalingEnabled() && gc != null) ? gc.getDefaultTransform().getScaleX() : 1; } @@ -297,11 +311,17 @@ public class UIScale } } + /** + * Returns the user scale factor. + */ public static float getUserScaleFactor() { initialize(); return scaleFactor; } + /** + * Sets the user scale factor. + */ private static void setUserScaleFactor( float scaleFactor ) { if( scaleFactor <= 1f ) scaleFactor = 1f; @@ -318,40 +338,65 @@ public class UIScale changeSupport.firePropertyChange( "userScaleFactor", oldScaleFactor, scaleFactor ); } + /** + * Multiplies the given value by the user scale factor. + */ public static float scale( float value ) { initialize(); return (scaleFactor == 1) ? value : (value * scaleFactor); } + /** + * Multiplies the given value by the user scale factor and rounds the result. + */ public static int scale( int value ) { initialize(); return (scaleFactor == 1) ? value : Math.round( value * scaleFactor ); } /** - * Similar as scale(int) but always "rounds down". + * Similar as {@link #scale(int)} but always "rounds down". + *

+ * For use in special cases. {@link #scale(int)} is the preferred method. */ public static int scale2( int value ) { initialize(); return (scaleFactor == 1) ? value : (int) (value * scaleFactor); } + /** + * Divides the given value by the user scale factor. + */ public static float unscale( float value ) { initialize(); return (scaleFactor == 1f) ? value : (value / scaleFactor); } + /** + * Divides the given value by the user scale factor and rounds the result. + */ public static int unscale( int value ) { initialize(); return (scaleFactor == 1f) ? value : Math.round( value / scaleFactor ); } + /** + * If user scale factor is not 1, scale the given graphics context by invoking + * {@link Graphics2D#scale(double, double)} with user scale factor. + */ public static void scaleGraphics( Graphics2D g ) { initialize(); if( scaleFactor != 1f ) g.scale( scaleFactor, scaleFactor ); } + /** + * Scales the given dimension with the user scale factor. + *

+ * If user scale factor is 1, then the given dimension is simply returned. + * Otherwise a new instance of {@link Dimension} or {@link DimensionUIResource} + * is returned, depending on whether the passed dimension implements {@link UIResource}. + */ public static Dimension scale( Dimension dimension ) { initialize(); return (dimension == null || scaleFactor == 1f) @@ -361,6 +406,13 @@ public class UIScale : new Dimension ( scale( dimension.width ), scale( dimension.height ) )); } + /** + * Scales the given insets with the user scale factor. + *

+ * If user scale factor is 1, then the given insets is simply returned. + * Otherwise a new instance of {@link Insets} or {@link InsetsUIResource} + * is returned, depending on whether the passed dimension implements {@link UIResource}. + */ public static Insets scale( Insets insets ) { initialize(); return (insets == null || scaleFactor == 1f) diff --git a/flatlaf-extras/src/main/java/com/formdev/flatlaf/extras/components/FlatTabbedPane.java b/flatlaf-extras/src/main/java/com/formdev/flatlaf/extras/components/FlatTabbedPane.java index 7cd70ce2..bd04f9b4 100644 --- a/flatlaf-extras/src/main/java/com/formdev/flatlaf/extras/components/FlatTabbedPane.java +++ b/flatlaf-extras/src/main/java/com/formdev/flatlaf/extras/components/FlatTabbedPane.java @@ -164,14 +164,16 @@ public class FlatTabbedPane /** - * Returns the height of a tab. + * Returns the minimum height of a tab. */ public int getTabHeight() { return getClientPropertyInt( TABBED_PANE_TAB_HEIGHT, "TabbedPane.tabHeight" ); } /** - * Specifies the height of a tab. + * Specifies the minimum height of a tab. + * + * @see #setTabInsets(Insets) */ public void setTabHeight( int tabHeight ) { putClientProperty( TABBED_PANE_TAB_HEIGHT, (tabHeight >= 0) ? tabHeight : null ); @@ -187,6 +189,8 @@ public class FlatTabbedPane /** * Specifies the insets of a tab. + * + * @see #setTabHeight(int) */ public void setTabInsets( Insets tabInsets ) { putClientProperty( TABBED_PANE_TAB_INSETS, tabInsets ); @@ -203,6 +207,8 @@ public class FlatTabbedPane /** * Specifies the insets of the tab at the given tab index. + * + * @see #setTabHeight(int) */ public void setTabInsets( int tabIndex, Insets tabInsets ) { JComponent c = (JComponent) getComponentAt( tabIndex );