Class CSSGridTracks

java.lang.Object
com.iizix.prop.ui.CSSGridTracks

public final class CSSGridTracks extends Object
A parsed CSS Grid track list, the value of the columns, rows, autoColumns and autoRows properties of CSSGridLayout.

The property itself is a plain StringProp holding CSS text, e.g. "200px 1fr minmax(120px,2fr)". The Browser receives that text verbatim as grid-template-columns (or -rows, grid-auto-columns, grid-auto-rows), so the grammar accepted here is a subset of CSS and nothing else: every track the parser accepts is resolved natively by the Browser, with no measurement in JavaScript. This class is the single source of truth for validation in the Designer (the property sheet marker and the track dialog) and for any later editing of one track.

The accepted grammar (CSS Grid Layout Level 1, without line names and without subgrid, which are out of scope):

  template list   := ( track-size | repeat(N, track-size+) )+
                     with at most one repeat(auto-fill|auto-fit, fixed-size+), in which
                     case every other track must have a fixed size
  auto list       := track-size+                     (grid-auto-columns / -rows)
  track-size      := breadth | minmax(inflexible, breadth) | fit-content(length)
  breadth         := length | flex | auto | min-content | max-content
  inflexible      := length | auto | min-content | max-content
  fixed-size      := length | minmax(length, breadth) | minmax(inflexible, length)
  length          := number px|%|em|rem|vw|vh, or a unitless 0
  flex            := number fr
Numbers are non-negative decimals. Keywords, function names and units are case-insensitive and are written lower case by toString(). A blank string is a valid, empty list ("no explicit tracks").

IIZI units are not accepted (dlg, dpx, dpr, the neighbor units, formulas): they would have to be computed in JavaScript, which is what this layout exists to avoid. % here is the CSS % of the grid container's content box, not IIZI's %.

Instances are immutable.

Author:
Christopher Mindus
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    The kind of one track or track function.
    static final class 
    One track, track function or repetition.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    The repeat count of repeat(auto-fill,...).
    static final int
    The repeat count of repeat(auto-fit,...).
    static final CSSGridTracks
    The empty list.
    static final List<String>
    The units accepted for a length, in the order they are listed in messages.
    static final int
    The largest integer repeat count accepted (the Browsers clamp the total track count near this value anyway).
  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    Two lists are equal when their canonical CSS texts are equal.
    int
    Returns the number of explicit tracks.
    Returns the tracks.
    boolean
    Returns if the list holds repeat(auto-fill,...) or repeat(auto-fit,...).
    int
    Hash code of the canonical CSS text.
    boolean
    Returns if the list is empty.
    boolean
    Returns if any track grows with a flexible length fr.
    of(List<CSSGridTracks.Track> tracks, boolean auto)
    Creates a list from tracks, validating it against the template grammar or the auto grammar.
    parse(String text)
    Parses a track template (grid-template-columns / -rows).
    Parses an implicit track list (grid-auto-columns / -rows): one or more track sizes, no repeat().
    Returns the CSS text in canonical form: tracks separated by one space, functions written without spaces after their commas, numbers without redundant zeros, everything lower case.
    static String
    validate(String text, boolean auto)
    Validates a text.

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • LENGTH_UNITS

      public static final List<String> LENGTH_UNITS
      The units accepted for a length, in the order they are listed in messages.
    • AUTO_FILL

      public static final int AUTO_FILL
      The repeat count of repeat(auto-fill,...).
      See Also:
    • AUTO_FIT

      public static final int AUTO_FIT
      The repeat count of repeat(auto-fit,...).
      See Also:
    • MAX_REPEAT

      public static final int MAX_REPEAT
      The largest integer repeat count accepted (the Browsers clamp the total track count near this value anyway).
      See Also:
    • EMPTY

      public static final CSSGridTracks EMPTY
      The empty list.
  • Method Details

    • of

      public static CSSGridTracks of(List<CSSGridTracks.Track> tracks, boolean auto)
      Creates a list from tracks, validating it against the template grammar or the auto grammar.
      Parameters:
      tracks - The tracks.
      auto - true for the grid-auto-columns/-rows grammar (no repeat()).
      Returns:
      The list.
      Throws:
      IllegalArgumentException - When the combination is not valid CSS.
    • parse

      public static CSSGridTracks parse(String text) throws ParseException
      Parses a track template (grid-template-columns / -rows).
      Parameters:
      text - The CSS text, null or blank for an empty list.
      Returns:
      The parsed list.
      Throws:
      ParseException - When the text is not in the accepted grammar; the error offset is the index in text where the problem was found.
    • parseAuto

      public static CSSGridTracks parseAuto(String text) throws ParseException
      Parses an implicit track list (grid-auto-columns / -rows): one or more track sizes, no repeat().
      Parameters:
      text - The CSS text, null or blank for an empty list (the CSS initial value auto).
      Returns:
      The parsed list.
      Throws:
      ParseException - When the text is not in the accepted grammar.
    • validate

      public static String validate(String text, boolean auto)
      Validates a text.
      Parameters:
      text - The CSS text.
      auto - true for the auto-track grammar, false for the template grammar.
      Returns:
      null when valid, otherwise the error message (including the position).
    • getTracks

      public List<CSSGridTracks.Track> getTracks()
      Returns the tracks.
      Returns:
      The unmodifiable list.
    • isEmpty

      public boolean isEmpty()
      Returns if the list is empty.
      Returns:
      true for no tracks.
    • getTrackCount

      public int getTrackCount()
      Returns the number of explicit tracks.
      Returns:
      The count, or -1 when it depends on the container size (auto-fill, auto-fit).
    • isFlexible

      public boolean isFlexible()
      Returns if any track grows with a flexible length fr.
      Returns:
      true when flexible.
    • hasAutoRepeat

      public boolean hasAutoRepeat()
      Returns if the list holds repeat(auto-fill,...) or repeat(auto-fit,...).
      Returns:
      true for an automatic repetition.
    • toString

      public String toString()
      Returns the CSS text in canonical form: tracks separated by one space, functions written without spaces after their commas, numbers without redundant zeros, everything lower case. Parsing the result gives an equal list.
      Overrides:
      toString in class Object
    • equals

      public boolean equals(Object obj)
      Two lists are equal when their canonical CSS texts are equal.
      Overrides:
      equals in class Object
    • hashCode

      public int hashCode()
      Hash code of the canonical CSS text.
      Overrides:
      hashCode in class Object