FlowCellConf.java

  1. package swingtree.layout;

  3. import com.google.errorprone.annotations.Immutable;
  4. import org.slf4j.Logger;
  5. import org.slf4j.LoggerFactory;
  6. import swingtree.UI;
  7. import swingtree.UIForAnySwing;
  8. import swingtree.api.Configurator;

  10. import java.util.Arrays;
  11. import java.util.Objects;

  13. /**
  14.  *  An immutable configuration object used to define how a {@link FlowCell} should
  15.  *  place its associated component within a {@link ResponsiveGridFlowLayout}.<br>
  16.  *  Instances of this are passed to the {@link swingtree.api.Configurator} of a {@link FlowCell}
  17.  *  so that you can dynamically assign the number of cells a component should span,
  18.  *  based on the size category of the parent container.<br>
  19.  *  <br>
  20.  *  Use {@link UI#AUTO_SPAN(Configurator)} to create a {@link FlowCell} from a {@link Configurator}
  21.  *  and pass it to the {@link swingtree.UIForAnySwing#add(AddConstraint, UIForAnySwing[])}
  22.  *  of a SwingTree UI declaration.<br>
  23.  *  Here an example demonstrating how this might be used:
  24.  *  <pre>{@code
  25.  *    UI.panel().withPrefSize(400, 300)
  26.  *    .withFlowLayout()
  27.  *    .add(UI.AUTO_SPAN( it->it.small(12).medium(6).large(8) ),
  28.  *         html("A red cell").withStyle(it->it
  29.  *             .backgroundColor(UI.Color.RED)
  30.  *         )
  31.  *    )
  32.  *    .add(UI.AUTO_SPAN( it->it.small(12).medium(6).large(4) ),
  33.  *         html("a green cell").withStyle(it->it
  34.  *             .backgroundColor(Color.GREEN)
  35.  *         )
  36.  *    )
  37.  *  }</pre>
  38.  *  In the above example, the {@code it} parameter of the {@code Configurator} is an instance of this class.
  39.  *  The {@link Configurator} is called every time the {@link ResponsiveGridFlowLayout} updates the layout
  40.  *  of the parent container, so that the number of cells a component spans can be adjusted dynamically.<br>
  41.  *  The {@link UIForAnySwing#withFlowLayout()} creates a {@link ResponsiveGridFlowLayout} and attaches it to the panel.<br>
  42.  *  <p><b>
  43.  *      Note that the {@link FlowCell} configuration may only take effect if the parent
  44.  *      container has a {@link ResponsiveGridFlowLayout} as a {@link java.awt.LayoutManager} installed.
  45.  *  </b>
  46.  *  <br><br>
  47.  *  <p>
  48.  *  Besides configuring the number of cells to span, you can also
  49.  *  define how the cell should be filled vertically by the component
  50.  *  and how the component should be aligned vertically within the cell.<br>
  51.  *  Use the {@link #fill(boolean)} method to set the fill flag to {@code true}
  52.  *  if you want the component to fill the cell vertically.<br>
  53.  *  Use the {@link #align(UI.VerticalAlignment)} method to set the vertical alignment
  54.  *  of the component within the cell to either {@link UI.VerticalAlignment#TOP},
  55.  *  {@link UI.VerticalAlignment#CENTER}, or {@link UI.VerticalAlignment#BOTTOM}.
  56.  */
  57. @Immutable
  58. public final class FlowCellConf
  59. {
  60.     private static final Logger log = LoggerFactory.getLogger(FlowCellConf.class);
  61.     private final int                    _maxCellsToFill;
  62.     private final Size                   _parentSize;
  63.     private final ParentSizeClass        _parentSizeCategory;
  64.     @SuppressWarnings("Immutable")
  65.     private final FlowCellSpanPolicy[]   _autoSpans;
  66.     private final boolean                _fill;
  67.     private final UI.VerticalAlignment   _verticalAlignment;


  70.     FlowCellConf(
  71.             int                  maxCellsToFill,
  72.             Size                 parentSize,
  73.             ParentSizeClass      parentSizeCategory,
  74.             FlowCellSpanPolicy[] autoSpans,
  75.             boolean              fill,
  76.             UI.VerticalAlignment alignVertically
  77.     ) {
  78.         _maxCellsToFill     = maxCellsToFill;
  79.         _parentSize         = Objects.requireNonNull(parentSize);
  80.         _parentSizeCategory = Objects.requireNonNull(parentSizeCategory);
  81.         _autoSpans          = Objects.requireNonNull(autoSpans.clone());
  82.         _fill               = fill;
  83.         _verticalAlignment = alignVertically;
  84.     }

  86.     FlowCellSpanPolicy[] autoSpans() {
  87.         return _autoSpans.clone();
  88.     }

  90.     /**
  91.      *  Returns the maximum number of cells that a component can span
  92.      *  in a grid layout managed by a {@link ResponsiveGridFlowLayout}.<br>
  93.      *  The default value is 12, which is the maximum number of cells in a row
  94.      *  of the {@link ResponsiveGridFlowLayout}.
  95.      *  You may use this value to respond to it dynamically in the {@link Configurator}.
  96.      *
  97.      *  @return The maximum number of cells that a component can span in a grid layout.
  98.      */
  99.     public int maxCellsToFill() {
  100.         return _maxCellsToFill;
  101.     }

  103.     /**
  104.      *  Returns the {@link Size} object that represents the parent container's size.
  105.      *  The cell exposes this information so that you can use for a more
  106.      *  informed decision on how many cells a component should span.
  107.      *
  108.      *  @return The width and height of the parent container of the component
  109.      *          associated with this cell span configuration.
  110.      */
  111.     public Size parentSize() {
  112.         return _parentSize;
  113.     }

  115.     /**
  116.      *  Returns the {@link ParentSizeClass} category that represents the parent container's width
  117.      *  relative to its preferred width.<br>
  118.      *  The cell exposes this information so that you can use for a more
  119.      *  informed decision on how many cells a component should span.<br>
  120.      *  <p>
  121.      *  The {@link ParentSizeClass} category is calculated by dividing the parent container's width
  122.      *  by the preferred width of the parent container. <br>
  123.      *  So a parent container is considered large if its size is close to the preferred size,
  124.      *  and {@link ParentSizeClass#OVERSIZE} if it is significantly larger.
  125.      *
  126.      *  @return The category of the parent container's size.
  127.      */
  128.     public ParentSizeClass parentSizeCategory() {
  129.         return _parentSizeCategory;
  130.     }

  132.     /**
  133.      *  Returns a new and updated {@link FlowCellConf} instance with an additional
  134.      *  {@link FlowCellSpanPolicy} that specifies the number of cells to fill
  135.      *  for a given {@link ParentSizeClass} category.<br>
  136.      *
  137.      *  @param size The {@link ParentSizeClass} category to set.
  138.      *  @param cellsToFill The number of cells to fill.
  139.      *  @return A new {@link FlowCellConf} instance with the given {@link ParentSizeClass} and number of cells to fill.
  140.      */
  141.     public FlowCellConf with( ParentSizeClass size, int cellsToFill ) {
  142.         Objects.requireNonNull(size);
  143.         if ( cellsToFill < 0 ) {
  144.             log.warn(
  145.                     "Encountered negative number '"+cellsToFill+"' for cells " +
  146.                     "to fill as part of the '"+ResponsiveGridFlowLayout.class.getSimpleName()+"' layout.",
  147.                     new Throwable()
  148.                 );
  149.             cellsToFill = 0;
  150.         } else if ( cellsToFill > _maxCellsToFill ) {
  151.             log.warn(
  152.                     "Encountered number '"+cellsToFill+"' for cells to fill that is greater " +
  153.                     "than the maximum number of cells to fill '"+_maxCellsToFill+"' " +
  154.                     "as part of the '"+ResponsiveGridFlowLayout.class.getSimpleName()+"' layout.",
  155.                     new Throwable()
  156.                 );
  157.             cellsToFill = _maxCellsToFill;
  158.         }
  159.         FlowCellSpanPolicy[] autoSpans = new FlowCellSpanPolicy[_autoSpans.length+1];
  160.         System.arraycopy(_autoSpans, 0, autoSpans, 0, _autoSpans.length);
  161.         autoSpans[_autoSpans.length] = FlowCellSpanPolicy.of(size, cellsToFill);
  162.         return new FlowCellConf(_maxCellsToFill, _parentSize, _parentSizeCategory, autoSpans, _fill, _verticalAlignment);
  163.     }

  165.     /**
  166.      *  Returns a new and updated {@link FlowCellConf} instance with an additional
  167.      *  {@link FlowCellSpanPolicy} that specifies the number of cells to fill
  168.      *  when the parent container is categorized as {@link ParentSizeClass#VERY_SMALL}.<br>
  169.      *  A parent container is considered "very small" if its width
  170.      *  is between 0/5 and 1/5 of its preferred width.<br>
  171.      *  <p>
  172.      *  The supplied number of cells to fill should be in the inclusive range of 0 to {@link #maxCellsToFill()}.<br>
  173.      *  Values outside this range will be clamped to the nearest valid value and a warning will be logged.
  174.      *
  175.      *  @param span The number of cells to span as part of a grid
  176.      *                     with a total of {@link #maxCellsToFill()} number of cells horizontally.
  177.      *  @return A new {@link FlowCellConf} instance with the given number of cells to fill
  178.      *          for the {@link ParentSizeClass#VERY_SMALL} category.
  179.      */
  180.     public FlowCellConf verySmall( int span ) {
  181.         return with(ParentSizeClass.VERY_SMALL, span);
  182.     }

  184.     /**
  185.      *  Returns a new and updated {@link FlowCellConf} instance with an additional
  186.      *  {@link FlowCellSpanPolicy} that specifies the number of cells to fill
  187.      *  when the parent container is categorized as {@link ParentSizeClass#SMALL}.<br>
  188.      *  A parent container is considered "small" if its width
  189.      *  is between 1/5 and 2/5 of its preferred width.<br>
  190.      *  <p>
  191.      *  The supplied number of cells to fill should be in the inclusive range of 0 to {@link #maxCellsToFill()}.<br>
  192.      *  Values outside this range will be clamped to the nearest valid value and a warning will be logged.
  193.      *
  194.      *  @param span The number of cells to span as part of a grid
  195.      *                     with a total of {@link #maxCellsToFill()} number of cells horizontally.
  196.      *  @return A new {@link FlowCellConf} instance with the given number of cells to fill
  197.      *          for the {@link ParentSizeClass#SMALL} category.
  198.      */
  199.     public FlowCellConf small( int span ) {
  200.         return with(ParentSizeClass.SMALL, span);
  201.     }

  203.     /**
  204.      *  Returns a new and updated {@link FlowCellConf} instance with an additional
  205.      *  {@link FlowCellSpanPolicy} that specifies the number of cells to fill
  206.      *  when the parent container is categorized as {@link ParentSizeClass#MEDIUM}.<br>
  207.      *  A parent container is considered "medium" if its width
  208.      *  is between 2/5 and 3/5 of its preferred width.<br>
  209.      *  <p>
  210.      *  The supplied number of cells to fill should be in the inclusive range of 0 to {@link #maxCellsToFill()}.<br>
  211.      *  Values outside this range will be clamped to the nearest valid value and a warning will be logged.
  212.      *
  213.      *  @param span The number of cells to span as part of a grid
  214.      *                     with a total of {@link #maxCellsToFill()} number of cells horizontally.
  215.      *  @return A new {@link FlowCellConf} instance with the given number of cells to fill
  216.      *          for the {@link ParentSizeClass#MEDIUM} category.
  217.      */
  218.     public FlowCellConf medium( int span ) {
  219.         return with(ParentSizeClass.MEDIUM, span);
  220.     }

  222.     /**
  223.      *  Returns a new and updated {@link FlowCellConf} instance with an additional
  224.      *  {@link FlowCellSpanPolicy} that specifies the number of cells to fill
  225.      *  when the parent container is categorized as {@link ParentSizeClass#LARGE}.<br>
  226.      *  A parent container is considered "large" if its width
  227.      *  is between 3/5 and 4/5 of its preferred width.<br>
  228.      *  <p>
  229.      *  The supplied number of cells to fill should be in the inclusive range of 0 to {@link #maxCellsToFill()}.<br>
  230.      *  Values outside this range will be clamped to the nearest valid value and a warning will be logged.
  231.      *
  232.      *  @param span The number of cells to span as part of a grid
  233.      *                     with a total of {@link #maxCellsToFill()} number of cells horizontally.
  234.      *  @return A new {@link FlowCellConf} instance with the given number of cells to fill
  235.      *          for the {@link ParentSizeClass#LARGE} category.
  236.      */
  237.     public FlowCellConf large( int span ) {
  238.         return with(ParentSizeClass.LARGE, span);
  239.     }

  241.     /**
  242.      *  Returns a new and updated {@link FlowCellConf} instance with an additional
  243.      *  {@link FlowCellSpanPolicy} that specifies the number of cells to fill
  244.      *  when the parent container is categorized as {@link ParentSizeClass#VERY_LARGE}.<br>
  245.      *  A parent container is considered "very large" if its width
  246.      *  is between 4/5 and 5/5 of its preferred width.<br>
  247.      *  <p>
  248.      *  The supplied number of cells to fill should be in the inclusive range of 0 to {@link #maxCellsToFill()}.<br>
  249.      *  Values outside this range will be clamped to the nearest valid value and a warning will be logged.
  250.      *
  251.      *  @param span The number of cells to span as part of a grid
  252.      *                     with a total of {@link #maxCellsToFill()} number of cells horizontally.
  253.      *  @return A new {@link FlowCellConf} instance with the given number of cells to fill
  254.      *          for the {@link ParentSizeClass#VERY_LARGE} category.
  255.      */
  256.     public FlowCellConf veryLarge( int span ) {
  257.         return with(ParentSizeClass.VERY_LARGE, span);
  258.     }

  260.     /**
  261.      *  Returns a new and updated {@link FlowCellConf} instance with an additional
  262.      *  {@link FlowCellSpanPolicy} that specifies the number of cells to fill
  263.      *  when the parent container is categorized as {@link ParentSizeClass#OVERSIZE}.<br>
  264.      *  A parent container is considered "oversize" if its width is greater than its preferred width.<br>
  265.      *  <p>
  266.      *  The supplied number of cells to fill should be in the inclusive range of 0 to {@link #maxCellsToFill()}.<br>
  267.      *  Values outside this range will be clamped to the nearest valid value and a warning will be logged.
  268.      *
  269.      *  @param span The number of cells to span as part of a grid
  270.      *                     with a total of {@link #maxCellsToFill()} number of cells horizontally.
  271.      *  @return A new {@link FlowCellConf} instance with the given number of cells to fill
  272.      *          for the {@link ParentSizeClass#OVERSIZE} category.
  273.      */
  274.     public FlowCellConf oversize( int span ) {
  275.         return with(ParentSizeClass.OVERSIZE, span);
  276.     }

  278.     boolean fill() {
  279.         return _fill;
  280.     }

  282.     /**
  283.      *  This flag defines how the grid cell in the flow layout should be filled
  284.      *  by the component to which this cell configuration belongs.<br>
  285.      *  The default behavior is to not fill the cell, but rather to align the component
  286.      *  vertically in the center of the cell and use the component's preferred height.<br>
  287.      *  If this flag is set to {@code true}, the component will fill the cell vertically
  288.      *  and use the full height of the cell, which is also the full height of the row.<br>
  289.      *  Note that this will ignore the component's preferred height!
  290.      *
  291.      * @param fill Whether the cell should be filled by the component.
  292.      * @return A new {@link FlowCellConf} instance with the given fill flag.
  293.      */
  294.     public FlowCellConf fill(boolean fill) {
  295.         return new FlowCellConf(_maxCellsToFill, _parentSize, _parentSizeCategory, _autoSpans, fill, _verticalAlignment);
  296.     }

  298.     UI.VerticalAlignment verticalAlignment() {
  299.         return _verticalAlignment;
  300.     }

  302.     /**
  303.      *  The {@link UI.VerticalAlignment} of a flow cell tells the
  304.      *  {@link ResponsiveGridFlowLayout} how to place the component
  305.      *  vertically within the cell.<br>
  306.      *  So if you want the component to be aligned at the top,
  307.      *  use {@link UI.VerticalAlignment#TOP}, if you want it to be
  308.      *  centered, use {@link UI.VerticalAlignment#CENTER}, and if you
  309.      *  want it to be aligned at the bottom, use {@link UI.VerticalAlignment#BOTTOM}.
  310.      *
  311.      * @param alignment The vertical alignment of the component within the cell.
  312.      * @return A new {@link FlowCellConf} instance with the given vertical alignment policy.
  313.      */
  314.     public FlowCellConf align(UI.VerticalAlignment alignment) {
  315.         return new FlowCellConf(_maxCellsToFill, _parentSize, _parentSizeCategory, _autoSpans, _fill, alignment);
  316.     }

  318.     @Override
  319.     public String toString() {
  320.         return this.getClass().getSimpleName() + "[" +
  321.                     "maxCellsToFill="     + _maxCellsToFill + ", " +
  322.                     "parentSize="         + _parentSize + ", " +
  323.                     "parentSizeCategory=" + _parentSizeCategory + ", " +
  324.                     "autoSpans="          + _autoSpans.length + ", " +
  325.                     "fill="               + _fill + ", " +
  326.                     "alignVertically="    + _verticalAlignment +
  327.                 "]";
  328.     }

  330.     @Override
  331.     public boolean equals(Object obj) {
  332.         if ( obj == this ) {
  333.             return true;
  334.         }
  335.         if ( obj == null || obj.getClass() != this.getClass() ) {
  336.             return false;
  337.         }
  338.         FlowCellConf that = (FlowCellConf)obj;
  339.         return this._maxCellsToFill == that._maxCellsToFill
  340.             && this._parentSize.equals(that._parentSize)
  341.             && this._parentSizeCategory == that._parentSizeCategory
  342.             && this._autoSpans.length == that._autoSpans.length
  343.             && Arrays.deepEquals(this._autoSpans, that._autoSpans)
  344.             && this._fill == that._fill
  345.             && this._verticalAlignment == that._verticalAlignment;
  346.     }

  348.     @Override
  349.     public int hashCode() {
  350.         return Objects.hash(_maxCellsToFill, _parentSize, _parentSizeCategory, Arrays.hashCode(_autoSpans), _fill, _verticalAlignment);
  351.     }
  352. }
Created with JaCoCo 0.8.11.202310140853