Class GUnit

Method Details

• createGUnit

  public static GUnit createGUnit(String expr0, String... specialValues) throws GUnitException

  Creates a GUnit object from a String. The String must be in the formats:

   - [+|-] nnn [unit]
   - [+|-] nnn[.ddd] [unit]
   - a formula built from numbers, unit suffixes, the operators "+-*/", parentheses
     and the functions min(), max() and clamp()
  

  A value that is a single number with at most one unit suffix and an optional sign becomes a simple unit, exactly as before; anything else becomes a UT_FORMULA.

  Parameters:

  expr0 - The expression string.

  specialValues - Accepted special values.

  Returns:

  GUnit the created unit.

  Throws:

  GUnitException - The error message. The instance is a FormulaException carrying the offset and length of the error in expr0, so a caller wanting to place a caret can test for that subclass.

• createCSSGUnit

  public static GUnit createCSSGUnit(String value, String... specialValues) throws GUnitException

  Creates a GUnit object from a String. The String must be in the formats:

   - [+|-] nnn [unit]
   - [+|-] nnn[.ddd] [unit]
  

  All formats except "pixel" supports decimals ([.ddd] above).

  Formulas are not supported. The following units are supported:

  • px: pixel,
  • pt: point,
  • em: width of "M",
  • ex: width of "x",
  • %: percentage width of parent,
  • vw: viewport width,
  • vh: viewport height,
  • rem: root element font size.

  Parameters:

  value - The value string.

  specialValues - Accepted special values.

  Returns:

  GUnit the created unit.

  Throws:

  GUnitException - The error message.

• validateCSSGUnit

  public static void validateCSSGUnit(GUnit unit, String... specialValues) throws GUnitException

  Validates a GUnit object.

  Formulas are not supported. The following units are supported:

  • px: pixel,
  • pt: point,
  • em: width of "M",
  • ex: width of "x",
  • %: percentage width of parent,
  • vw: viewport width,
  • vh: viewport height,
  • rem: root element font size.

  Parameters:

  unit - The unit as CSS value.

  specialValues - Accepted special values.

  Throws:

  GUnitException - The error message.

• getType

  public int getType()

  Gets the type of the unit (0-29), one of the values:

  • UT_PX (pixel),
  • UT_DLG (dialog),
  • UT_EM ("em"),
  • UT_EX ("ex"),
  • UT_PT (point),
  • UT_PC (percent),
  • UT_PCW (percentage of parent width),
  • UT_PCH (percentage of parent height),
  • UT_PCMIN (minimum size of percentage of parent width and height),
  • UT_PCMAX (maximum size of percentage of parent width and height),
  • UT_VW (percentage of viewport width),
  • UT_VH (percentage of viewport height),
  • UT_VMIN (size for minimum size of percentage of viewport width and height),
  • UT_VMAX (size for maximum size of percentage of viewport width and height),
  • UT_NL (size of the notch LEFT side safe size in pixels),
  • UT_NR (size of the notch RIGHT side safe size in pixels),
  • UT_NW (notch cutout bounding-box WIDTH in screen space, in pixels),
  • UT_NT (size of the notch TOP side safe size in pixels),
  • UT_NB (size of the notch BOTTOM side safe size in pixels),
  • UT_CWMIN (the component's own computed CSS "min-width"),
  • UT_CWMAX (the component's own computed CSS "max-width"),
  • UT_CHMIN (the component's own computed CSS "min-height"),
  • UT_CHMAX (the component's own computed CSS "max-height"),
  • UT_REM (the root element font size),
  • UT_DPX (one physical device pixel in CSS pixels),
  • UT_DPR (the device pixel ratio itself, a multiplier and not a length),
  • UT_NH (notch cutout bounding-box HEIGHT in screen space, in pixels),
  • UT_NX (offset along the top or bottom edge to the LEFT side of the notch),
  • UT_NY (offset along the left or right edge to the TOP of the notch),
  • UT_FORMULA (formula) or
  • UT_VALUE (special value).

  Returns:

  The unit type.

• getFormula

  public Formula getFormula()

  Gets the compiled program of a UT_FORMULA unit.

  Returns:

  The compiled formula, or null when this is not a UT_FORMULA.

• getFormulaSource

  public String getFormulaSource()

  Gets the formula as normalised source text, generated from the opcode array.

  This is a DISPLAY ARTEFACT, not the text the author typed: spacing is normalised and only precedence- and associativity-required parentheses are emitted. Nothing may parse this string at runtime.

  Parenthesis minimisation is not an optimisation pass and costs nothing to leave on: the opcode array holds no parentheses to begin with, so every call regenerates the minimum set from the tree. ((((1%+(((2em+3ex)/2))))+10)/3) comes back as (1% + (2em + 3ex) / 2 + 10) / 3 -- six pairs down to two, both load-bearing.

  Deliberately distinct from toString(), which keeps the behaviour the previous GUnit always had.

  Returns:

  The formula source, or null if this unit is not a formula.

• simplifyFormula

  public GUnit simplifyFormula() throws GUnitException

  Simplifies the formula by folding constant subexpressions.

  7+(1+(2*3)) becomes 14. Folding stops at a SCALE, so 10%+5 is already minimal: 10% is not known until evaluation.

  Parenthesis minimisation is NOT part of this: it happens on every getFormulaSource() call, because the opcode array contains no parentheses to begin with. Only constant folding discards something the developer wrote, which is why only folding is an explicit action. It must never run automatically -- a developer may have written 2*3 because it is 2 columns by 3 rows and intends to edit it, and regenerating the display text through a folder would silently eat that.

  The result is still a UT_FORMULA even when it has folded to a single constant. It is deliberately not collapsed to a simple unit: a simple pixel value may not carry decimals, so simplifying 1.5+1 would have to throw rather than return the 2.5 it just computed.

  The previous GUnit was immutable and GUnit stays that way, so this returns a new instance rather than folding in place. A property value is very likely shared and cached across the property tree, and a mutating simplify in one editor would change an instance another component is holding.

  Returns:

  A new simplified GUnit, or this when the formula is already minimal and nothing changed. The caller's test is an identity comparison, if ( simplified!=gu ).

  Throws:

  GUnitException - If this unit is not a formula.

• isLocked

  public boolean isLocked()

  Checks if the unit is "locked" from user change in the GUI design editor.

  Returns:

  The lock flag.

• setLocked

  public void setLocked(boolean on)

  Sets the lock state of the unit.

  Parameters:

  on - The lock flag.

• getString

  public String getString()

  Gets the String representation of the bounds as "value type".

  Returns:

  A string in the form of value type.

• isZero

  public boolean isZero()

  Checks if the unit is zero.

  Returns:

  true if the value is zero when not a UT_FORMULA or UT_VALUE string such as "fixed", false otherwise.

• equals

  public boolean equals(Object o)

  Checks if two unit objects are equal.

  Overrides:

  equals in class Object

  Parameters:

  o - another unit object. If null, the units are not equal.

  Returns:

  true if the object has the same type and value.

• equals

  public boolean equals(GUnit unit)

  Checks if two unit objects are equal.

  Two formulas are equal when they are the same PROGRAM, i.e. identical opcodes and constants, rather than when their text happens to match. The text is regenerated from the opcodes so the two are equivalent, but comparing the program says what is meant.

  Parameters:

  unit - another size object. If null, the sizes are not equal.

  Returns:

  true if the object has the same type and value.

• hashCode

  public int hashCode()

  Returns the hash code of this unit.

  Overrides:

  hashCode in class Object

  Returns:

  The hash code.

• clone

  public GUnit clone()

  Clones this instance.

  Overrides:

  clone in class Object

  Returns:

  As cloned instance of GUnit.

• paramString

  protected String paramString()

  Returns the parameter string representing the state of this event. This string is useful for debugging. Super-classes adds extra information to the string by preceding it with a comma followed by the extra information.

  For a UT_FORMULA the text is REGENERATED from the opcodes, with normalised spacing. It is a display artefact; nothing parses it back at runtime.

  Returns:

  the parameter string of this unit object.

• getValue

  public double getValue()

  Returns the double value for the unit.

  Returns:

  The value for every simple unit type, or Double.NaN for UT_FORMULA and UT_VALUE.

• toString

  public String toString()

  Returns a string representation of this class instance.

  Overrides:

  toString in class Object

  Returns:

  A string representation of this class instance.

• getCSSValue

  public String getCSSValue()

  Gets the unit as a CSS value. Formula and percent is NOT accepted and returns null along with a warning logging.

  Returns:

  The CSS value, or null if it's a UT_FORMULA.

• append

  public void append(SendTransaction trans)

  Appends the unit object to a transaction.

  Only the UT_FORMULA branch differs from the previous GUnit: it writes the opcode array rather than a control-character string. UT_VALUE still writes a string and a simple value still writes the signed integer, the decimal digit count and, when there are decimals, the decimal part. A formula's constants reuse that same triple, which is both smaller than a text number for fractions and already readable by the client.

  Parameters:

  trans - The transaction.

• validate

  public String validate() throws GUnitException

  Validates an expression formula by evaluating it against a neutral scale table, i.e. one where every unit resolves to 1.0 except the reciprocal pair dpx and dpr.

  Parsing IS validation now, so by the time an instance exists the formula is known to be well formed; this method remains as a smoke test that evaluation terminates and produces a number, and as the value the Designer shows.

  Returns:

  The evaluated value as a string, or null when this is not a UT_FORMULA.

  Throws:

  GUnitException - For validation errors.

• evalDouble

  public double evalDouble(IScaleProvider scales, int axis)

  Evaluates the formula and returns the raw, unrounded pixel value.

  This overload builds a scale table on every call. When both axes are evaluated for the same element, which is the normal layout case, build the table once with UnitType.fillCommon(IScaleProvider,double[]), swap the two axis-dependent slots with UnitType.fillAxis(IScaleProvider,double[],int) and call evaluate(double[]) instead.

  Parameters:

  scales - The value provider.

  axis - AXIS_X or AXIS_Y.

  Returns:

  The value, or Double.NaN when this is not a UT_FORMULA.

• evalRounded

  public double evalRounded(IScaleProvider scales, int axis)

  Evaluates the formula and rounds the result to DEFAULT_DECIMALS decimals.

  Parameters:

  scales - The value provider.

  axis - AXIS_X or AXIS_Y.

  Returns:

  The rounded value.

• evalRounded

  public double evalRounded(IScaleProvider scales, int axis, int decimals)

  Evaluates the formula and rounds the result to a given number of decimals.

  Parameters:

  scales - The value provider.

  axis - AXIS_X or AXIS_Y.

  decimals - The number of decimals, 0 to 7.

  Returns:

  The rounded value.

  Throws:

  IllegalArgumentException - If the decimal count is out of range.

• evalInt

  public int evalInt(IScaleProvider scales, int axis)

  Evaluates the formula and rounds the result to a whole pixel.

  Parameters:

  scales - The value provider.

  axis - AXIS_X or AXIS_Y.

  Returns:

  The value as an integer number of CSS pixels.

• evalSnapped

  public double evalSnapped(IScaleProvider scales, int axis)

  Evaluates the formula and snaps the result to the DEVICE PIXEL GRID.

  Snapping is a DIFFERENT operation from decimal rounding: three decimals preserves precision through the arithmetic, snapping aligns the final result to hardware. If both are wanted, snapping goes last. At a device pixel ratio of 2 this permits 0.5px positions, which are exact device pixels, giving twice the positional resolution of integer rounding and letting a 1dpx border land on exactly one physical pixel.

  Callers should snap cumulative OFFSETS and derive each size as the difference, i.e. size[i] = snap(pos[i+1]) - snap(pos[i]). Rounding each item's size independently accumulates error, so item edges stop meeting exactly and a bordered list gets a 1px gap here and an overlap there. Edges then meet by construction, and individual items differing by a pixel is invisible where misaligned borders are not.

  Parameters:

  scales - The value provider.

  axis - AXIS_X or AXIS_Y.

  Returns:

  The snapped value.

• evaluate

  public double evaluate(double[] scaleTable)

  Evaluates the compiled formula against a prepared scale table. THE EVALUATOR.

  A loop over a switch and a fixed stack. The stack never grows and is never indexed out of bounds, because the parser computes the peak depth of the program at compile time and rejects anything above Formula.MAX_STACK_DEPTH; the depth grows with parenthesis nesting only, never with argument count, since variadic min() and max() are folded pairwise.

  MIN2 and MAX2 are a plain compare rather than Math.min/Math.max: faster, and it avoids having to replicate JavaScript's -0 and NaN rules exactly in Java. The consequence is that a NaN as the right operand loses the comparison and is discarded rather than propagating. A non-finite result is clamped to 0 once, at the end, so NaN never escapes either way.

  Parameters:

  scaleTable - The scale table, see UnitType.

  Returns:

  The value, or Double.NaN when this is not a UT_FORMULA.

• getPixelValue

  public double getPixelValue(UIComp comp, boolean isHorz)

  Calculates the unit into a pixel value using the font information.

  A unit typed alone resolves exactly as the same unit inside a formula. Every unit except the four font units reads the SAME IScaleProvider the UT_FORMULA branch uses, through providerScale(IScaleProvider,int,int), so 100% and 100%+0px return the same number, and so do 100cwmax and 100cwmax+0px. Only the ONE getter for the unit in question is called; no scale table is built, because this runs per layout. The font units are not routed there because they already agree by identity: both paths read the same comp.getFontInfo().

  The notch values are therefore no longer hardcoded to zero as they are in the previous GUnit. They still evaluate to zero in the Designer, but because the provider has nothing to report there rather than because this method says so.

  BEHAVIOUR CHANGE against the previous GUnit, 2026-08-17, and it is a visible one. The nine percent and viewport units used to read UIComp.getPixelWidth()/getPixelHeight() here and return NaN when the container declared nothing, while a formula read UIComp.getApproximateSize() -- a hardcoded Size(300,200) on a plain container. Both now take the two-level chain in

  invalid reference

  UICompScaleProvider#containerDimension(UIContainer,boolean)

  . Two consequences:

  • Every existing FORMULA using a percent or viewport unit changes value, from a constant-based number to one derived from the container's real declared size.
  • A SIMPLE percent unit no longer yields NaN when the container declares no size; it falls back like everything else. UIComp.getPixelWidth() maps that NaN to -1, so a component declaring 100% under an undeclared parent used to report "no width" and now reports a number. -1 consequently narrows to its literal meaning: no layout, or no unit declared at all.

  Parameters:

  comp - The component.

  isHorz - Flag indicating this is a horizontal value (significant only for % or DLG).

  Returns:

  The pixel value, or Double.NaN if the expression is invalid.

  Throws:

  IllegalStateException - If this is called outside of the Designer.

• isPureCSS

  public boolean isPureCSS()

  Checks if this is a valid CSS pure unit, e.g. not DLG, Formula.

  Returns:

  true if it's a pure CSS unit, false if it is a calculated value and cannot be used in CSS declarations.

• isContainerDependent

  public boolean isContainerDependent()

  Returns if this value is dependent on the container size, i.e. value is a percent value or a formula containing percent.

  Behaviour change against the previous GUnit, deliberate. It tests the formula with the anchored regular expression ^[\x06-\x0A]+$, which requires the ENTIRE formula to consist of percent markers and therefore answers false for every formula that also contains a number, i.e. for every real formula. Here the question asked is the one the javadoc always described: does the program use any percent unit.

  Returns:

  true if the value is container dependent, i.e. a Percent value, or if it is a formula that contains a percent value. false is returned if the value is not dependent of the container.