org.gjt.sp.jedit.gui

## Class ExtendedGridLayout

- java.lang.Object
- - org.gjt.sp.jedit.gui.ExtendedGridLayout

- All Implemented Interfaces:
    java.awt.LayoutManager, java.awt.LayoutManager2

      public class ExtendedGridLayout
      extends java.lang.Object
      implements java.awt.LayoutManager2

  A layout manager that places components in a rectangular grid with variable cell sizes that supports colspans and rowspans.

  The container is divided into rectangles, and each component is placed in a rectangular space defined by its colspan and rowspan. Each row is as large as the largest component in that row, and each column is as wide as the widest component in that column.

  This behavior is similar to `java.awt.GridLayout` but it supports different row heights and column widths for each row/column.

  For example, the following is a Dialog that lays out ten buttons exactly the same as in the example of the JavaDoc of `java.awt.GridBagLayout` with the difference of vertical and horizontal gaps that can be configured:

  >         1:import java.awt.Button;
  >         2:import java.awt.Dimension;
  >         3:
  >         4:import javax.swing.JDialog;
  >         5:
  >         6:import org.gjt.sp.jedit.gui.ExtendedGridLayout;
  >         7:import org.gjt.sp.jedit.gui.ExtendedGridLayoutConstraints;
  >         8:
  >         9:import static org.gjt.sp.jedit.gui.ExtendedGridLayoutConstraints.REMAINDER;
  >        10:
  >        11:public class ExampleDialog extends JDialog {
  >        12:    public ExampleDialog() {
  >        13:        super(null,"Example Dialog",true);
  >        14:        setLayout(new ExtendedGridLayout(5,5,new Insets(5,5,5,5)));
  >        15:
  >        16:        add(makeButton("Button1"));
  >        17:        add(makeButton("Button2"));
  >        18:        add(makeButton("Button3"));
  >        19:        add(makeButton("Button4"));
  >        20:        Button button = makeButton("Button5");
  >        21:        add(button,new ExtendedGridLayoutConstraints(1,REMAINDER,1,button));
  >        22:        button = makeButton("Button6");
  >        23:        add(button,new ExtendedGridLayoutConstraints(2,3,1,button));
  >        24:        button = makeButton("Button7");
  >        25:        add(button,new ExtendedGridLayoutConstraints(2,button));
  >        26:        button = makeButton("Button8");
  >        27:        add(button,new ExtendedGridLayoutConstraints(3,1,2,button));
  >        28:        button = makeButton("Button9");
  >        29:        add(button,new ExtendedGridLayoutConstraints(3,3,1,button));
  >        30:        button = makeButton("Button10");
  >        31:        add(button,new ExtendedGridLayoutConstraints(4,REMAINDER,1,button));
  >        32:
  >        33:        pack();
  >        34:        setLocationRelativeTo(null);
  >        35:        setVisible(true);
  >        36:    }
  >        37:
  >        38:    private Button makeButton(String name) {
  >        39:        Button button = new Button(name);
  >        40:        button.setMaximumSize(new Dimension(Integer.MAX_VALUE,Integer.MAX_VALUE));
  >        41:        return button;
  >        42:    }
  >        43:}

  If you use `REMAINDER` as colspan or rowspan then a component takes up the remaining space in that column or row. Any additional components in a row are ignored and not displayed. Additional components in a column are moved rightside. If a rowspan hits a colspan, the colspan ends and the rowspan takes precedence.

  Components for which `isVisible() == false` are ignored. Because of this, components can be replaced "in-place" by adding two components next to each other, with different `isVisible()` values, and toggling the `setVisible()` values of both when we wish to swap the currently visible component with the one that is hidden.

  If you want to reserve free space in a row inbetween components, add a `javax.swing.Box.Filler` to the layout if the free space is in the middle of a row, or just don't add components if the free space should be at the end of a row.

  If a row is taller, or a column is wider than the `maximumSize` of a component, the component is resized to its maximum size and aligned according to its `alignmentX` and `alignmentY` values.

  One instance of this class can be used to layout multiple containers at the same time.

  See Also:
    `ExtendedGridLayoutConstraints`, `java.awt.Component`, `javax.swing.Box.Filler`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ExtendedGridLayout()` Creates an extended grid layout manager with zero horizontal and vertical gap, and zero distance to the borders of the parent container.
    `ExtendedGridLayout(int hgap, int vgap, java.awt.Insets distanceToBorders)` Creates an extended grid layout manager with the specified horizontal and vertical gap, and the specified distance to the borders of the parent container.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addLayoutComponent(java.awt.Component component, java.lang.Object constraints)` Adds the specified component to the layout, using the specified constraints object.
    `void` | `addLayoutComponent(java.lang.String name, java.awt.Component component)` If the layout manager uses a per-component string, adds the component `component` to the layout, associating it with the string specified by `name`.
    `float` | `getLayoutAlignmentX(java.awt.Container container)` Returns the alignment along the X axis.
    `float` | `getLayoutAlignmentY(java.awt.Container container)` Returns the alignment along the Y axis.
    `void` | `invalidateLayout(java.awt.Container container)` Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.
    `void` | `layoutContainer(java.awt.Container parent)` Lays out the specified container.
    `java.awt.Dimension` | `maximumLayoutSize(java.awt.Container parent)` Calculates the maximum size dimensions for the specified container, given the components it contains.
    `java.awt.Dimension` | `minimumLayoutSize(java.awt.Container parent)` Calculates the minimum size dimensions for the specified container, given the components it contains.
    `java.awt.Dimension` | `preferredLayoutSize(java.awt.Container parent)` Calculates the preferred size dimensions for the specified container, given the components it contains.
    `void` | `removeLayoutComponent(java.awt.Component component)` Removes the specified component from the layout.
    `java.lang.String` | `toString()` Returns a string representation of the object.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### ExtendedGridLayout

          public ExtendedGridLayout(int hgap,
                            int vgap,
                            java.awt.Insets distanceToBorders)

      Creates an extended grid layout manager with the specified horizontal and vertical gap, and the specified distance to the borders of the parent container.
      Parameters:
        `hgap` - The horizontal space between two columns (>=0)
        `vgap` - The vertical space between two rows (>=0)
        `distanceToBorders` - The distances to the borders of the parent container
      Throws:
        `java.lang.IllegalArgumentException` - if hgap < 0
        `java.lang.IllegalArgumentException` - if vgap < 0

    - #### ExtendedGridLayout

          public ExtendedGridLayout()

      Creates an extended grid layout manager with zero horizontal and vertical gap, and zero distance to the borders of the parent container.

  - ### Method Detail

    - #### addLayoutComponent

          public void addLayoutComponent(java.lang.String name,
                                java.awt.Component component)

      If the layout manager uses a per-component string, adds the component `component` to the layout, associating it with the string specified by `name`.
      Specified by:
        `addLayoutComponent` in interface `java.awt.LayoutManager`
      Parameters:
        `name` - The string to be associated with the component. Has to be `null`, so that default constraints are used.
        `component` - The component to be added
      Throws:
        `java.lang.IllegalArgumentException` - if `name` is not `null`
      See Also:
        `addLayoutComponent(java.awt.Component, java.lang.Object)`

    - #### addLayoutComponent

          public void addLayoutComponent(java.awt.Component component,
                                java.lang.Object constraints)

      Adds the specified component to the layout, using the specified constraints object.
      Specified by:
        `addLayoutComponent` in interface `java.awt.LayoutManager2`
      Parameters:
        `component` - The component to be added
        `constraints` - Where/how the component is added to the layout.
      Throws:
        `java.lang.IllegalArgumentException` - if `constraints` is not an ExtendedGridLayoutConstraints object
        `java.lang.IllegalArgumentException` - if `constraints` is a placeholder
        `java.lang.IllegalArgumentException` - if `constraints` is not the right one for the component
      See Also:
        `ExtendedGridLayoutConstraints`

    - #### removeLayoutComponent

          public void removeLayoutComponent(java.awt.Component component)

      Removes the specified component from the layout.
      Specified by:
        `removeLayoutComponent` in interface `java.awt.LayoutManager`
      Parameters:
        `component` - The component to be removed

    - #### getLayoutAlignmentX

          public float getLayoutAlignmentX(java.awt.Container container)

      Returns the alignment along the X axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.
      Specified by:
        `getLayoutAlignmentX` in interface `java.awt.LayoutManager2`
      Parameters:
        `container` - The container for which the alignment should be returned
      Returns:
        `java.awt.Component.CENTER_ALIGNMENT`

    - #### getLayoutAlignmentY

          public float getLayoutAlignmentY(java.awt.Container container)

      Returns the alignment along the Y axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.
      Specified by:
        `getLayoutAlignmentY` in interface `java.awt.LayoutManager2`
      Parameters:
        `container` - The container for which the alignment should be returned
      Returns:
        `java.awt.Component.CENTER_ALIGNMENT`

    - #### minimumLayoutSize

          public java.awt.Dimension minimumLayoutSize(java.awt.Container parent)

      Calculates the minimum size dimensions for the specified container, given the components it contains.
      Specified by:
        `minimumLayoutSize` in interface `java.awt.LayoutManager`
      Parameters:
        `parent` - The component to be laid out
      Returns:
        The minimum size for the container
      See Also:
        `maximumLayoutSize(java.awt.Container)`, `preferredLayoutSize(java.awt.Container)`

    - #### preferredLayoutSize

          public java.awt.Dimension preferredLayoutSize(java.awt.Container parent)

      Calculates the preferred size dimensions for the specified container, given the components it contains.
      Specified by:
        `preferredLayoutSize` in interface `java.awt.LayoutManager`
      Parameters:
        `parent` - The container to be laid out
      Returns:
        The preferred size for the container
      See Also:
        `maximumLayoutSize(java.awt.Container)`, `minimumLayoutSize(java.awt.Container)`

    - #### maximumLayoutSize

          public java.awt.Dimension maximumLayoutSize(java.awt.Container parent)

      Calculates the maximum size dimensions for the specified container, given the components it contains.
      Specified by:
        `maximumLayoutSize` in interface `java.awt.LayoutManager2`
      Parameters:
        `parent` - The container to be laid out
      Returns:
        The maximum size for the container
      See Also:
        `minimumLayoutSize(java.awt.Container)`, `preferredLayoutSize(java.awt.Container)`

    - #### invalidateLayout

          public void invalidateLayout(java.awt.Container container)

      Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.
      Specified by:
        `invalidateLayout` in interface `java.awt.LayoutManager2`
      Parameters:
        `container` - The container for which the cached information should be discarded

    - #### layoutContainer

          public void layoutContainer(java.awt.Container parent)

      Lays out the specified container.
      Specified by:
        `layoutContainer` in interface `java.awt.LayoutManager`
      Parameters:
        `parent` - The container to be laid out

    - #### toString

          public java.lang.String toString()

      Returns a string representation of the object. In general, the `toString` method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of the object.