GraphUI Layout: Emphasize whether a value/parameter is scaled or unscaled in API doc to ease usage

6 files changed, 76 insertions, 72 deletions

diff --git a/src/graphui/classes/com/jogamp/graph/ui/Shape.java b/src/graphui/classes/com/jogamp/graph/ui/Shape.java
index 05d562363..3ef55c1f6 100644
--- a/src/graphui/classes/com/jogamp/graph/ui/Shape.java
+++ b/src/graphui/classes/com/jogamp/graph/ui/Shape.java
@@ -330,10 +330,10 @@ public abstract class Shape {
     public final Shape setVisible(final boolean v) { return setIO(IO_VISIBLE, v); }
 
     /**
-     * Sets the padding for this shape, which is included in {@link #getBounds()} and also includes the border. Default is zero.
-     *
+     * Sets the unscaled padding for this shape, which is included in unscaled {@link #getBounds()} and also includes the border. Default is zero.
+     * <p>
      * Method issues {@link #markShapeDirty()}.
-     *
+     * </p>
      * @param padding distance of shape to the border, i.e. padding
      * @return this shape for chaining
      * @see #getPadding()
@@ -346,7 +346,7 @@ public abstract class Shape {
     }
 
     /**
-     * Returns {@link Padding} of this shape, which is included in {@link #getBounds()B} and also includes the border. Default is zero.
+     * Returns unscaled {@link Padding} of this shape, which is included in unscaled {@link #getBounds()} and also includes the border. Default is zero.
      * @see #setPaddding(Padding)
      * @see #hasPadding()
      */
diff --git a/src/graphui/classes/com/jogamp/graph/ui/layout/BoxLayout.java b/src/graphui/classes/com/jogamp/graph/ui/layout/BoxLayout.java
index 4c654f535..3c3039284 100644
--- a/src/graphui/classes/com/jogamp/graph/ui/layout/BoxLayout.java
+++ b/src/graphui/classes/com/jogamp/graph/ui/layout/BoxLayout.java
@@ -44,8 +44,8 @@ import com.jogamp.math.util.PMVMatrix4f;
  * <ul>
  *   <li>Optionally centered {@link Alignment.Bit#CenterHoriz horizontally}, {@link Alignment.Bit#CenterVert vertically} or {@link Alignment#Center both}.</li>
  *   <li>Optionally scaled to cell-size if given and {@link Alignment#Fill}</li>
- *   <li>{@link Padding} is applied to each {@Shape} via {@link Shape#setPaddding(Padding)} if passed in constructor and is scaled if {@link Alignment.Bit#Fill}</li>
- *   <li>{@link Margin} is applied unscaled if used and ignored with only center {@link Alignment} w/o {@link Alignment.Bit#Fill} scale</li>
+ *   <li>Unscaled {@link Padding} is applied to each {@Shape} via {@link Shape#setPaddding(Padding)} if passed in constructor and is scaled if {@link Alignment.Bit#Fill}</li>
+ *   <li>Scaled {@link Margin} is applied unscaled if used and ignored with only center {@link Alignment} w/o additional scaling</li>
  *   <li>Not implemented {@link Alignment}: {@link Alignment.Bit#Top Top}, {@link Alignment.Bit#Right Right}, {@link Alignment.Bit#Bottom Bottom}, {@link Alignment.Bit#Left Left}</li>
  * </ul>
  * </p>
@@ -53,8 +53,10 @@ import com.jogamp.math.util.PMVMatrix4f;
 public class BoxLayout implements Group.Layout {
     private final Vec2f cellSize;
     private final Alignment alignment;
-    private final Margin margin; // unscaled
-    private final Padding padding; // scaled
+    /** Scaled {@link Margin} value is applied w/o additional scaling. */
+    private final Margin margin;
+    /** Unscaled {@link Padding} value. */
+    private final Padding padding;
 
     private static final boolean TRACE_LAYOUT = false;
 
@@ -67,7 +69,7 @@ public class BoxLayout implements Group.Layout {
 
     /**
      *
-     * @param padding {@link Padding} applied to each {@Shape} via {@link Shape#setPaddding(Padding)} and is scaled if {@link Alignment.Bit#Fill}
+     * @param padding unscaled {@link Padding} applied to each {@Shape} via {@link Shape#setPaddding(Padding)} and is scaled if {@link Alignment.Bit#Fill}
      */
     public BoxLayout(final Padding padding) {
         this(0f, 0f, Alignment.None, Margin.None, padding);
@@ -87,7 +89,7 @@ public class BoxLayout implements Group.Layout {
      *
      * @param cellWidth optional cell width, zero for none
      * @param cellHeight optional cell height, zero for none
-     * @param margin {@link Margin} is applied unscaled and ignored with only center {@link Alignment} w/o {@link Alignment.Bit#Fill} scale
+     * @param margin scaled {@link Margin} is applied unscaled and ignored with only center {@link Alignment} w/o additional scaling
      */
     public BoxLayout(final float cellWidth, final float cellHeight, final Margin margin) {
         this(cellWidth, cellHeight, Alignment.None, margin, null);
@@ -97,7 +99,7 @@ public class BoxLayout implements Group.Layout {
      *
      * @param cellWidth optional cell width, zero for none
      * @param cellHeight optional cell height, zero for none
-     * @param padding {@link Padding} applied to each {@Shape} via {@link Shape#setPaddding(Padding)} and is scaled if {@link Alignment.Bit#Fill}
+     * @param padding unscaled {@link Padding} applied to each {@Shape} via {@link Shape#setPaddding(Padding)} and is scaled if {@link Alignment.Bit#Fill}
      */
     public BoxLayout(final float cellWidth, final float cellHeight, final Padding padding) {
         this(cellWidth, cellHeight, Alignment.None, Margin.None, padding);
@@ -107,8 +109,8 @@ public class BoxLayout implements Group.Layout {
      *
      * @param cellWidth optional cell width, zero for none
      * @param cellHeight optional cell height, zero for none
-     * @param margin {@link Margin} is applied unscaled and ignored with only center {@link Alignment} w/o {@link Alignment.Bit#Fill} scale
-     * @param padding {@link Padding} applied to each {@Shape} via {@link Shape#setPaddding(Padding)} and is scaled if {@link Alignment.Bit#Fill}
+     * @param margin scaled {@link Margin} is applied unscaled and ignored with only center {@link Alignment} w/o additional scaling
+     * @param padding unscaled {@link Padding} applied to each {@Shape} via {@link Shape#setPaddding(Padding)} and is scaled if {@link Alignment.Bit#Fill}
      */
     public BoxLayout(final float cellWidth, final float cellHeight, final Margin margin, final Padding padding) {
         this(cellWidth, cellHeight, Alignment.None, margin, padding);
@@ -118,7 +120,7 @@ public class BoxLayout implements Group.Layout {
      *
      * @param cellWidth optional cell width, zero for none
      * @param cellHeight optional cell height, zero for none
-     * @param margin {@link Margin} is applied unscaled
+     * @param margin scaled {@link Margin} is applied unscaled
      */
     public BoxLayout(final float cellWidth, final float cellHeight, final Alignment alignment, final Margin margin) {
         this(cellWidth, cellHeight, alignment, margin, null);
@@ -129,7 +131,7 @@ public class BoxLayout implements Group.Layout {
      * @param cellWidth optional cell width, zero for none
      * @param cellHeight optional cell height, zero for none
      * @param alignment
-     * @param padding {@link Padding} applied to each {@Shape} via {@link Shape#setPaddding(Padding)} and is scaled if {@link Alignment.Bit#Fill}
+     * @param padding unscaled {@link Padding} applied to each {@Shape} via {@link Shape#setPaddding(Padding)} and is scaled if {@link Alignment.Bit#Fill}
      */
     public BoxLayout(final float cellWidth, final float cellHeight, final Alignment alignment, final Padding padding) {
         this(cellWidth, cellHeight, alignment, Margin.None, padding);
@@ -140,8 +142,8 @@ public class BoxLayout implements Group.Layout {
      * @param cellWidth optional cell width, zero for none
      * @param cellHeight optional cell height, zero for none
      * @param alignment
-     * @param margin {@link Margin} is applied unscaled and ignored with only center {@link Alignment} w/o {@link Alignment.Bit#Fill} scale
-     * @param padding {@link Padding} applied to each {@Shape} via {@link Shape#setPaddding(Padding)} and is scaled if {@link Alignment.Bit#Fill}
+     * @param margin scaled {@link Margin} is applied unscaled and ignored with only center {@link Alignment} w/o additional scaling
+     * @param padding unscaled {@link Padding} applied to each {@Shape} via {@link Shape#setPaddding(Padding)} and is scaled if {@link Alignment.Bit#Fill}
      */
     public BoxLayout(final float cellWidth, final float cellHeight, final Alignment alignment, final Margin margin, final Padding padding) {
         this.cellSize = new Vec2f(Math.max(0f, cellWidth), Math.max(0f, cellHeight));
@@ -155,9 +157,9 @@ public class BoxLayout implements Group.Layout {
     public Vec2f getCellSize() { return cellSize; }
     /** Returns given {@link Alignment}. */
     public Alignment getAlignment() { return alignment; }
-    /** Returns given {@link Margin}. */
+    /** Returns given scaled {@link Margin}. */
     public Margin getMargin() { return margin; }
-    /** Returns given {@link Padding}, may be {@code null} if not given via constructor. */
+    /** Returns given unscaled {@link Padding}, may be {@code null} if not given via constructor. */
     public Padding getPadding() { return padding; }
 
     @Override
diff --git a/src/graphui/classes/com/jogamp/graph/ui/layout/Gap.java b/src/graphui/classes/com/jogamp/graph/ui/layout/Gap.java
index 9d832092d..7e3484cf9 100644
--- a/src/graphui/classes/com/jogamp/graph/ui/layout/Gap.java
+++ b/src/graphui/classes/com/jogamp/graph/ui/layout/Gap.java
@@ -30,7 +30,7 @@ package com.jogamp.graph.ui.layout;
 import com.jogamp.math.FloatUtil;
 
 /**
- * GraphUI CSS property Gap, spacing between (grid) cells not belonging to the element.
+ * GraphUI CSS property Gap, scaled spacing between (grid) cells not belonging to the cell element.
  * <p>
  * The CSS gap property defines the size of the gap between the rows and columns in a grid layout.
  * </p>
@@ -39,9 +39,9 @@ public class Gap {
     /** Zero gap constant. */
     public static final Gap None = new Gap();
 
-    /** Row gap value, vertical spacing. */
+    /** Scaled row gap value, vertical spacing. */
     public final float row;
-    /** Column gap value, horizontal spacing. */
+    /** Scaled column gap value, horizontal spacing. */
     public final float column;
 
     private Gap() {
@@ -50,8 +50,8 @@ public class Gap {
 
     /**
      * Ctor
-     * @param row vertical row value
-     * @param column horizontal column value
+     * @param row scaled vertical row value
+     * @param column scaled horizontal column value
      */
     public Gap(final float row, final float column) {
         this.row = row; this.column = column;
@@ -59,16 +59,16 @@ public class Gap {
 
     /**
      * Ctor
-     * @param rc vertical row and horizontal column value
+     * @param rc scaled vertical row and horizontal column value
      */
     public Gap(final float rc) {
         this.row = rc; this.column = rc;
     }
 
-    /** Return width of horizontal value, i.e. 1 * column. */
+    /** Return scaled width of horizontal value, i.e. 1 * column. */
     public float width() { return column; }
 
-    /** Return height of vertical value, i.e. 1 * row. */
+    /** Return scaled height of vertical value, i.e. 1 * row. */
     public float height() { return row; }
 
     public boolean zeroSumWidth() { return FloatUtil.isZero( width() ); };
diff --git a/src/graphui/classes/com/jogamp/graph/ui/layout/GridLayout.java b/src/graphui/classes/com/jogamp/graph/ui/layout/GridLayout.java
index 88c046280..704116d2c 100644
--- a/src/graphui/classes/com/jogamp/graph/ui/layout/GridLayout.java
+++ b/src/graphui/classes/com/jogamp/graph/ui/layout/GridLayout.java
@@ -44,9 +44,9 @@ import com.jogamp.math.util.PMVMatrix4f;
  * <ul>
  *   <li>Optionally centered {@link Alignment.Bit#CenterHoriz horizontally}, {@link Alignment.Bit#CenterVert vertically} or {@link Alignment#Center both}.</li>
  *   <li>Optionally scaled to cell-size if given and {@link Alignment#Fill}</li>
- *   <li>{@link Padding} is applied to each {@Shape} via {@link Shape#setPaddding(Padding)} if passed in constructor and is scaled if {@link Alignment.Bit#Fill}</li>
+ *   <li>Unscaled {@link Padding} is applied to each {@Shape} via {@link Shape#setPaddding(Padding)} if passed in constructor and is scaled if {@link Alignment.Bit#Fill}</li>
  *   <li>Without cell-size behaves like a grid bag using individual shape sizes including {@link Padding}</li>
- *   <li>{@link Gap} is applied unscaled if used.</li>
+ *   <li>Scaled {@link Gap} is applied unscaled if used.</li>
  *   <li>Can be filled in {@link Order#COLUMN} or {@link Order#ROW} major-order.</li>
  *   <li>Not implemented {@link Alignment}: {@link Alignment.Bit#Top Top}, {@link Alignment.Bit#Right Right}, {@link Alignment.Bit#Bottom Bottom}, {@link Alignment.Bit#Left Left}</li>
  *   <li>..</li>
@@ -66,8 +66,10 @@ public class GridLayout implements Group.Layout {
     private final int row_limit;
     private final Vec2f cellSize;
     private final Alignment alignment;
+    /** Scaled {@link Gap} value is applied w/o additional scaling. */
     private final Gap gap;
-    private final Padding padding; // scaled!
+    /** Unscaled {@link Padding} value. */
+    private final Padding padding;
     private int row_count, col_count;
 
     private static final boolean TRACE_LAYOUT = false;
@@ -89,7 +91,7 @@ public class GridLayout implements Group.Layout {
      * @param cellWidth
      * @param cellHeight
      * @param alignment TODO
-     * @param gap {@link Gap} is applied unscaled
+     * @param gap scaled {@link Gap} value is applied w/o additional scaling
      */
     public GridLayout(final int column_limit, final float cellWidth, final float cellHeight, final Alignment alignment, final Gap gap) {
         this(alignment, Math.max(1, column_limit), -1, cellWidth, cellHeight, gap, null);
@@ -101,8 +103,8 @@ public class GridLayout implements Group.Layout {
      * @param cellWidth
      * @param cellHeight
      * @param alignment TODO
-     * @param gap {@link Gap} is applied unscaled
-     * @param padding {@link Padding} applied to each {@Shape} via {@link Shape#setPaddding(Padding)} and is scaled if {@link Alignment.Bit#Fill}
+     * @param gap scaled {@link Gap} value is applied w/o additional scaling
+     * @param padding unscaled {@link Padding} applied to each {@Shape} via {@link Shape#setPaddding(Padding)} and is scaled if {@link Alignment.Bit#Fill}
      */
     public GridLayout(final int column_limit, final float cellWidth, final float cellHeight, final Alignment alignment, final Gap gap, final Padding padding) {
         this(alignment, Math.max(1, column_limit), -1, cellWidth, cellHeight, gap, padding);
@@ -124,7 +126,7 @@ public class GridLayout implements Group.Layout {
      * @param cellWidth
      * @param cellHeight
      * @param alignment TODO
-     * @param gap {@link Gap} is applied unscaled
+     * @param gap scaled {@link Gap} value is applied w/o additional scaling
      * @param row_limit [1..inf)
      */
     public GridLayout(final float cellWidth, final float cellHeight, final Alignment alignment, final Gap gap, final int row_limit) {
@@ -136,8 +138,8 @@ public class GridLayout implements Group.Layout {
      * @param cellWidth
      * @param cellHeight
      * @param alignment TODO
-     * @param gap {@link Gap} is applied unscaled
-     * @param padding {@link Padding} applied to each {@Shape} via {@link Shape#setPaddding(Padding)} and is scaled if {@link Alignment.Bit#Fill}
+     * @param gap scaled {@link Gap} value is applied w/o additional scaling
+     * @param padding unscaled {@link Padding} applied to each {@Shape} via {@link Shape#setPaddding(Padding)} and is scaled if {@link Alignment.Bit#Fill}
      * @param row_limit [1..inf)
      */
     public GridLayout(final float cellWidth, final float cellHeight, final Alignment alignment, final Gap gap, final Padding padding, final int row_limit) {
@@ -167,9 +169,9 @@ public class GridLayout implements Group.Layout {
     public Vec2f getCellSize() { return cellSize; }
     /** Returns given {@link Alignment}. */
     public Alignment getAlignment() { return alignment; }
-    /** Returns given {@link Gap}. */
+    /** Returns given scaled {@link Gap}. */
     public Gap getGap() { return gap; }
-    /** Returns given {@link Padding}, may be {@code null} if not given via constructor. */
+    /** Returns given unscaled {@link Padding}, may be {@code null} if not given via constructor. */
     public Padding getPadding() { return padding; }
 
     @Override
diff --git a/src/graphui/classes/com/jogamp/graph/ui/layout/Margin.java b/src/graphui/classes/com/jogamp/graph/ui/layout/Margin.java
index 9ed1d2612..adac8c329 100644
--- a/src/graphui/classes/com/jogamp/graph/ui/layout/Margin.java
+++ b/src/graphui/classes/com/jogamp/graph/ui/layout/Margin.java
@@ -30,7 +30,7 @@ package com.jogamp.graph.ui.layout;
 import com.jogamp.math.FloatUtil;
 
 /**
- * GraphUI CSS property Margin, space between or around elements and not included in the element's size.
+ * GraphUI CSS property Margin, scaled space between or around elements and not included in the element's size.
  * <p>
  * The CSS margin properties are used to create space around elements, outside of any defined borders.
  * </p>
@@ -42,13 +42,13 @@ public class Margin {
     /** Zero margin constant. */
     public static final Margin None = new Margin();
 
-    /** Top value */
+    /** Scaled top value */
     public final float top;
-    /** Right value */
+    /** Scaled right value */
     public final float right;
-    /** Bottom value */
+    /** Scaled bottom value */
     public final float bottom;
-    /** Left value */
+    /** Scaled left value */
     public final float left;
 
     private Margin() {
@@ -57,10 +57,10 @@ public class Margin {
 
     /**
      * Ctor
-     * @param top top value
-     * @param right right value
-     * @param bottom bottom value
-     * @param left left value
+     * @param top scaled top value
+     * @param right scaled right value
+     * @param bottom scaled bottom value
+     * @param left scaled left value
      */
     public Margin(final float top, final float right, final float bottom, final float left) {
         this.top = top;
@@ -71,9 +71,9 @@ public class Margin {
 
     /**
      * Ctor
-     * @param top top value
-     * @param rl right and left value
-     * @param bottom bottom value
+     * @param top scaled top value
+     * @param rl scaled right and left value
+     * @param bottom scaled bottom value
      */
     public Margin(final float top, final float rl, final float bottom) {
         this.top = top;
@@ -84,8 +84,8 @@ public class Margin {
 
     /**
      * Ctor
-     * @param tb top and bottom value
-     * @param rl right and left value
+     * @param tb scaled top and bottom value
+     * @param rl scaled right and left value
      */
     public Margin(final float tb, final float rl) {
         this.top = tb;
@@ -96,7 +96,7 @@ public class Margin {
 
     /**
      * Ctor
-     * @param trbl top, right, bottom and left value
+     * @param trbl scaled top, right, bottom and left value
      */
     public Margin(final float trbl) {
         this.top = trbl;
@@ -105,10 +105,10 @@ public class Margin {
         this.left = trbl;
     }
 
-    /** Return width of horizontal values top + right. Zero if {@link #isCenteredHoriz()}. */
+    /** Return scaled width of horizontal values top + right. Zero if {@link #isCenteredHoriz()}. */
     public float width() { return left + right; }
 
-    /** Return height of vertical values bottom + top. Zero if {@link #isCenteredVert()}. */
+    /** Return scaled height of vertical values bottom + top. Zero if {@link #isCenteredVert()}. */
     public float height() { return bottom + top; }
 
     public boolean zeroWidth() { return FloatUtil.isZero( width() ); };
diff --git a/src/graphui/classes/com/jogamp/graph/ui/layout/Padding.java b/src/graphui/classes/com/jogamp/graph/ui/layout/Padding.java
index c59f98d1e..9349e7af2 100644
--- a/src/graphui/classes/com/jogamp/graph/ui/layout/Padding.java
+++ b/src/graphui/classes/com/jogamp/graph/ui/layout/Padding.java
@@ -30,7 +30,7 @@ package com.jogamp.graph.ui.layout;
 import com.jogamp.math.FloatUtil;
 
 /**
- * GraphUI CSS property Padding, space belonging to the element and included in the element's size.
+ * GraphUI CSS property Padding, unscaled space belonging to the element and included in the element's size.
  * <p>
  * The CSS padding properties are used to generate space around an element's content, inside of any defined borders.
  * </p>
@@ -39,13 +39,13 @@ public class Padding {
     /** Zero padding constant. */
     public static final Padding None = new Padding();
 
-    /** Top value */
+    /** Top value (unscaled) */
     public final float top;
-    /** Right value */
+    /** Right value (unscaled) */
     public final float right;
-    /** Bottom value */
+    /** Bottom value (unscaled) */
     public final float bottom;
-    /** Left value */
+    /** Left value (unscaled) */
     public final float left;
 
     private Padding() {
@@ -54,10 +54,10 @@ public class Padding {
 
     /**
      * Ctor
-     * @param top top value
-     * @param right right value
-     * @param bottom bottom value
-     * @param left left value
+     * @param top unscaled top value
+     * @param right unscaled right value
+     * @param bottom unscaled bottom value
+     * @param left unscaled left value
      */
     public Padding(final float top, final float right, final float bottom, final float left) {
         this.top = top; this.right = right; this.bottom = bottom; this.left = left;
@@ -65,9 +65,9 @@ public class Padding {
 
     /**
      * Ctor
-     * @param top top value
-     * @param rl right and left value
-     * @param bottom bottom value
+     * @param top unscaled top value
+     * @param rl unscaled right and left value
+     * @param bottom unscaled bottom value
      */
     public Padding(final float top, final float rl, final float bottom) {
         this.top = top; this.right = rl; this.bottom = bottom; this.left = rl;
@@ -75,8 +75,8 @@ public class Padding {
 
     /**
      * Ctor
-     * @param tb top and bottom value
-     * @param rl right and left value
+     * @param tb unscaled top and bottom value
+     * @param rl unscaled right and left value
      */
     public Padding(final float tb, final float rl) {
         this.top = tb; this.right = rl; this.bottom = tb; this.left = rl;
@@ -84,16 +84,16 @@ public class Padding {
 
     /**
      * Ctor
-     * @param trbl top, right, bottom and left value
+     * @param trbl unscaled top, right, bottom and left value
      */
     public Padding(final float trbl) {
         this.top = trbl; this.right = trbl; this.bottom = trbl; this.left = trbl;
     }
 
-    /** Return width of horizontal values top + right. */
+    /** Return unscaled width of horizontal values top + right. */
     public float width() { return left + right; }
 
-    /** Return height of vertical values bottom + top. */
+    /** Return unscaled height of vertical values bottom + top. */
     public float height() { return bottom + top; }
 
     public boolean zeroWidth() { return FloatUtil.isZero( width() ); };