Class CSSGridLayout

All Implemented Interfaces:
EventListener, IGProp<GProp<?>[]>, IPropCnr, Cloneable
Direct Known Subclasses:
ECSSGridLayout

public class CSSGridLayout extends LayoutMgr<CSSGridData>
CSSGridLayout is a layout manager that lays out its components with the Browser's own CSS Grid (display: grid).

It is the native counterpart of GridLayout (the "Grid layout", a port of the SWT GridLayout that measures and places every child in JavaScript). Here the client only writes CSS: the column and row tracks, the gaps and the placement of each child, and the Browser sizes and places everything, including on a resize. Nothing is measured per child, and the layout is responsive by itself through fr, minmax() and repeat(auto-fill,...).

The properties, all optional:

  columns         StringProp  grid-template-columns, CSS track list (see CSSGridTracks)
  rows            StringProp  grid-template-rows, CSS track list
  autoColumns     StringProp  grid-auto-columns, track sizes of implicit columns
  autoRows        StringProp  grid-auto-rows, track sizes of implicit rows
  flow            IntProp     grid-auto-flow: 0=row, 1=column, 2=row dense, 3=column dense
  gapX, gapY      UnitProp    column-gap, row-gap (CSS units only)
  justifyContent  IntProp     justify-content: 0=start, 1=center, 2=end, 3=stretch,
                              4=space-between, 5=space-around, 6=space-evenly
  alignContent    IntProp     align-content, same values
  mx, my          UnitProp    minimum width and height of the grid
  $hscroll, $vscroll          the scroll settings shared by every layout

Units. Only CSS units are used, so the Browser resolves every value itself and the layout never needs a JavaScript re-layout on a container resize. A % in this layout is the CSS %: of the grid container for a track and a gap, of the grid area for a component's size. That differs from IIZI's % in the other layouts, which is computed against the parent container.

Placement. A child is auto-placed in document order by default and may be given an explicit start column and row with spans in both axes (see CSSGridData), so no filler components are needed for an empty cell. A hidden child frees its cell.

A new container with this layout gets one stretching column "1fr" in the Designer; the server side never needs computed sizes, so this class holds the properties and answers the size questions of the Designer markers only.

Author:
Christopher Mindus
  • Field Details

    • COLUMNS

      public static final String COLUMNS
      The name of the column track list property.
      See Also:
    • ROWS

      public static final String ROWS
      The name of the row track list property.
      See Also:
    • AUTO_COLUMNS

      public static final String AUTO_COLUMNS
      The name of the implicit column size property.
      See Also:
    • AUTO_ROWS

      public static final String AUTO_ROWS
      The name of the implicit row size property.
      See Also:
    • FLOW

      public static final String FLOW
      The name of the auto-placement flow property.
      See Also:
    • GAP_X

      public static final String GAP_X
      The name of the column gap property.
      See Also:
    • GAP_Y

      public static final String GAP_Y
      The name of the row gap property.
      See Also:
    • JUSTIFY_CONTENT

      public static final String JUSTIFY_CONTENT
      The name of the horizontal track distribution property.
      See Also:
    • ALIGN_CONTENT

      public static final String ALIGN_CONTENT
      The name of the vertical track distribution property.
      See Also:
    • FLOWS

      public static final String[] FLOWS
      The CSS values of the flow property, by index. Append-only: the index is stored.
    • CONTENT_ALIGNS

      public static final String[] CONTENT_ALIGNS
      The CSS values of justifyContent and alignContent, by index. Append-only: the index is stored.
    • DEFAULT_COLUMNS

      public static final String DEFAULT_COLUMNS
      The column track list of a new container in the Designer: one stretching column.
      See Also:
  • Constructor Details

    • CSSGridLayout

      public CSSGridLayout()
      Creates the layout without name with a null value.
    • CSSGridLayout

      public CSSGridLayout(Atom propertyAtom)
      Creates the layout with the specified name with a null value.
      Parameters:
      propertyAtom - the property atom.
    • CSSGridLayout

      public CSSGridLayout(Atom propertyAtom, GProp<?>[] properties) throws PropException
      Creates the layout with the specified name and properties.
      Parameters:
      propertyAtom - the property atom.
      properties - the property array value for the layout manager.
      Throws:
      PropException - as structural changes in containers on client is prohibited.
  • Method Details

    • clone

      public CSSGridLayout clone()
      Creates a clone out of this property. The cloning is overridden by the subclasses in order to handle cloning of its class variables appropriately.
      Overrides:
      clone in class LayoutMgr<CSSGridData>
    • createDefaultLayoutProp

      public CSSGridData createDefaultLayoutProp(UIComp uiComp)
      Creates the default LayoutProp to use for a new component that is inserted directly into the UIComps container.
      Specified by:
      createDefaultLayoutProp in class LayoutMgr<CSSGridData>
      Parameters:
      uiComp - The component requesting the default layout property.
      Returns:
      A new instance of the layout data of this layout manager.
    • getLayoutPropClass

      public Class<CSSGridData> getLayoutPropClass()
      Returns the class required for this layout property.
      Specified by:
      getLayoutPropClass in class LayoutMgr<CSSGridData>
      Returns:
      The class for the layout property required.
    • getColumns

      public String getColumns()
      Returns the column track list text.
      Returns:
      The CSS text, empty when not set.
    • setColumns

      public void setColumns(String tracks)
      Sets the column track list, e.g. "200px 1fr" or "repeat(auto-fill,minmax(160px,1fr))". The text is validated and stored in its canonical form; null or blank removes the property.
      Parameters:
      tracks - The CSS track list.
      Throws:
      IllegalArgumentException - When the text is not an accepted track list (the message says what and where).
    • getRows

      public String getRows()
      Returns the row track list text.
      Returns:
      The CSS text, empty when not set.
    • setRows

      public void setRows(String tracks)
      Sets the row track list; see setColumns(String).
      Parameters:
      tracks - The CSS track list, null or blank to remove.
      Throws:
      IllegalArgumentException - When the text is not an accepted track list.
    • setAutoColumns

      public void setAutoColumns(String tracks)
      Sets the size of the implicit columns (columns created by placement beyond the explicit ones), e.g. "minmax(100px,auto)".
      Parameters:
      tracks - One or more CSS track sizes, no repeat(); null or blank to remove.
      Throws:
      IllegalArgumentException - When the text is not an accepted track size list.
    • setAutoRows

      public void setAutoRows(String tracks)
      Sets the size of the implicit rows, e.g. "minmax(48px,auto)".
      Parameters:
      tracks - One or more CSS track sizes, no repeat(); null or blank to remove.
      Throws:
      IllegalArgumentException - When the text is not an accepted track size list.
    • setFlow

      public void setFlow(int flow)
      Sets the auto-placement flow.
      Parameters:
      flow - An index into FLOWS.
      Throws:
      IllegalArgumentException - For an index outside the table.
    • setGap

      public void setGap(GUnit gapX, GUnit gapY)
      Sets the gaps between columns and rows.
      Parameters:
      gapX - The column gap, null for no change.
      gapY - The row gap, null for no change.
      Throws:
      IllegalArgumentException - When a gap is not a pure CSS unit.
    • setContentAlign

      public void setContentAlign(int justify, int align)
      Sets how the tracks are distributed when they are smaller than the container.
      Parameters:
      justify - The horizontal distribution, an index into CONTENT_ALIGNS, -1 for no change.
      align - The vertical distribution, an index into CONTENT_ALIGNS, -1 for no change.
      Throws:
      IllegalArgumentException - For an index outside the table.
    • mustHaveWidth

      public boolean mustHaveWidth()
      Does this component require a width?
      Overrides:
      mustHaveWidth in class LayoutMgr<CSSGridData>
      Returns:
      Returns true if the horizontal scrollbar setting is "auto" or "scroll".
    • mustHaveHeight

      public boolean mustHaveHeight()
      Does this component require a height?
      Overrides:
      mustHaveHeight in class LayoutMgr<CSSGridData>
      Returns:
      Returns true if the vertical scrollbar setting is "auto" or "scroll".
    • hasWidth0

      protected boolean hasWidth0(CSSGridData layout)
      Verifies if the layout data gives the component a width. In a CSS grid the component gets the width of its area only when it fills it; otherwise only an explicit width counts. (A track grows, never a child: what the Grid layout calls "grab" is an fr track here.)
      Overrides:
      hasWidth0 in class LayoutMgr<CSSGridData>
      Parameters:
      layout - The layout data.
      Returns:
      true if the component fills its area horizontally or has a non-zero width.
    • hasHeight0

      protected boolean hasHeight0(CSSGridData layout)
      Verifies if the layout data gives the component a height; see hasWidth0(CSSGridData).
      Overrides:
      hasHeight0 in class LayoutMgr<CSSGridData>
      Parameters:
      layout - The layout data.
      Returns:
      true if the component fills its area vertically or has a non-zero height.
    • hasContainerLayoutImplicitWidth

      protected boolean hasContainerLayoutImplicitWidth()
      Verifies if this container has an implicit width due to e.g. children.
      Overrides:
      hasContainerLayoutImplicitWidth in class LayoutMgr<CSSGridData>
      Returns:
      true if an implicit width is present, false (default) otherwise.
    • hasContainerLayoutImplicitHeight

      protected boolean hasContainerLayoutImplicitHeight()
      Verifies if this container has an implicit height due to e.g. children.
      Overrides:
      hasContainerLayoutImplicitHeight in class LayoutMgr<CSSGridData>
      Returns:
      true if an implicit height is present, false (default) otherwise.
    • hasImplicitAlignFillX

      public boolean hasImplicitAlignFillX()
      Returns if the layout causes implicit horizontal fill of its container: a CSS Grid container whose layout data has a width (cx) fills its frame horizontally, whatever alignment its layout data gives, so that its fr tracks get the room; a container is an inline-block that otherwise shrinks to its content (owner ruling 2026-11-04, CSSG-D-15). Not in a CSS Grid parent: when the layout data is CSSGridData, the frame is the cell and the width is the size in the cell that the alignment places (CSSG-D-17).

      This is the Java twin of fillsFrame(cnr,horz) in iz/ui/CSSGridLayout.js, asked by the client's UIContainer.alwaysFillX(); UIContainer.hasImplicitAlignFillX() forwards here. A layout that has been replaced no longer answers for the container, so the stored alignment of its layout data applies again (as onPropDispose does in the client).

      Overrides:
      hasImplicitAlignFillX in class LayoutMgr<CSSGridData>
      Returns:
      true when the container's layout data has a width and is not CSSGridData.
    • hasImplicitAlignFillY

      public boolean hasImplicitAlignFillY()
      Returns if the layout causes implicit vertical fill of its container: a CSS Grid container whose layout data has a height (cy) fills its frame vertically; see hasImplicitAlignFillX(). The Java twin of fillsFrame(cnr,false) in iz/ui/CSSGridLayout.js, asked by the client's UIContainer.alwaysFillY().
      Overrides:
      hasImplicitAlignFillY in class LayoutMgr<CSSGridData>
      Returns:
      true when the container's layout data has a height and is not CSSGridData.