Package net.sf.jguiraffe.gui.layout

Class PercentLayoutBase

  • All Implemented Interfaces:
    Serializable
    Direct Known Subclasses:
    BorderLayout, ButtonLayout, PercentLayout
    public abstract class PercentLayoutBase
extends Object
implements Serializable

    The main class of the percent layout manager.

    Percent layout provides a table-like layout, which is organized in columns and rows, each of which defined by a CellConstraints object. With these constraints objects it is possible to set a cell's alignment and its minimum size. A cell can also be assigned weight factors for its height and width. If there is more space available than needed by the existing cells, the remaining space is divided and assigned to cells with a weight factor greater than 0. So each cell can be given a certain percentage of the remaining space, thus the name of this layout manager.

    Sometimes certain columns or rows in the layout should have the same size, even if they contain components with different preferred or minimum sizes. To achieve this, CellGroup objects can be added to this layout manager. These objects define the indices of the columns and rows, which belong to the same group. All cells in a group have the same initial size. To ensure that the affected cells have always the same size, their weight factors must also be equal.

    This class is an abstract base class that implements the complete layouting algorithm. There will be concrete implementations for different layout types that are based on the central percent layout functionality. These classes will serve as adapters for specific layouts; they will create a layout description that can be handled by this base class.

    The family of percent layout classes is independent on a concrete GUI library. It can work together e.g. with Swing or SWT. To achieve this access to the managed GUI components is encapsulated by the PercentLayoutPlatformAdapter interface. A platform specific implementation of this interface must be passed to an instance of this class.

    Note: The PercentLayout class is not thread safe. It should be accessed by a single thread (the GUI thread) only.

    Version:
    $Id: PercentLayoutBase.java 205 2012-01-29 18:29:57Z oheger $
    Author:
    Oliver Heger
    See Also:
    Serialized Form

    • Constructor Detail

      • PercentLayoutBase

        protected PercentLayoutBase()
        Creates a new, uninitialized instance of PercentLayoutBase. If this constructor is used, the concrete implementation of the initCells(PercentLayoutPlatformAdapter) method must perform all initialization.

      • PercentLayoutBase

        protected PercentLayoutBase​(int cols,
                            int rows)
        Creates a new instance of PercentLayoutBase and sets the numbers of the rows and columns. The constraints for the cells are set to default values.
        Parameters:
        cols - the number of columns
        rows - the number of rows

      • PercentLayoutBase

        protected PercentLayoutBase​(Collection<? extends CellConstraints> colConstr,
                            Collection<? extends CellConstraints> rowConstr)
        Creates a new instance of PercentLayoutBase and initializes it. The constraints for the columns and rows are specified in the passed collections, which must contain instances of CellConstraints.
        Parameters:
        colConstr - a collection with column constraints
        rowConstr - a collection with row constraints

      • PercentLayoutBase

        protected PercentLayoutBase​(String colConstr,
                            String rowConstr)
        Creates a new instance of PercentLayoutBase and initializes it. The column and row constraints are defined as strings. These strings must contain valid specifications of cell constraints as defined in the documentation of CellConstraints. As separators between two cell definitions the following characters can be used: " ,;".
        Parameters:
        colConstr - a string defining column constraints
        rowConstr - a string defining row constraints

    • Method Detail

      • getPlatformAdapter

        public PercentLayoutPlatformAdapter getPlatformAdapter()
        Returns the platform adapter associated with this layout class.
        Returns:
        the platform adapter

      • setPlatformAdapter

        public void setPlatformAdapter​(PercentLayoutPlatformAdapter platformAdapter)
        Sets the platform adapter for this layout manager. This adapter allows access to and manipulation of the managed components.
        Parameters:
        platformAdapter - the platform adapter to use

      • isCanShrink

        public boolean isCanShrink()
        Returns a flag whether this layout can shrink below its preferred size.
        Returns:
        a flag whether this layout can shrink below its preferred size

      • setCanShrink

        public void setCanShrink​(boolean canShrink)
        Sets a flag whether this layout can shrink below its preferred size. If this flag is set and the space available for the hosting container becomes smaller than the layout's preferred size, the layout tries to reduce its size further using the minimum size defined for the components contained.
        Parameters:
        canShrink - the shrink flag

      • getColumnCount

        public int getColumnCount()
        Returns the number of columns in this layout.
        Returns:
        the number of columns

      • getRowCount

        public int getRowCount()
        Returns the number of rows in this layout.
        Returns:
        the number of rows

      • getColumnConstraints

        public CellConstraints getColumnConstraints​(int idx)
        Returns the column constraints object for the column with the given index.
        Parameters:
        idx - the index (0 based)
        Returns:
        the column constraints object for this column

      • setColumnConstraints

        public void setColumnConstraints​(int idx,
                                 CellConstraints cc)
        Sets the column constraints object for the column with the given index.
        Parameters:
        idx - the index of the column (0 based)
        cc - the constraints object

      • getAllColumnConstraints

        public CellConstraints[] getAllColumnConstraints()
        Returns an array with the current column constraints.
        Returns:
        the column constraints

      • getRowConstraints

        public CellConstraints getRowConstraints​(int idx)
        Returns the row constraints object for the row with the given index.
        Parameters:
        idx - the index (0 based)
        Returns:
        the row constraints object for this row

      • setRowConstraints

        public void setRowConstraints​(int idx,
                              CellConstraints cc)
        Sets the row constraints object for the row with the given index.
        Parameters:
        idx - the index of the row (0 based)
        cc - the constraints object

      • getAllRowConstraints

        public CellConstraints[] getAllRowConstraints()
        Returns an array with the current row constraints.
        Returns:
        the row constraints

      • getColumnGroups

        public Collection<CellGroup> getColumnGroups()
        Returns an unmodifiable collection with the column groups defined for this layout. This collection may be empty, but never null.
        Returns:
        a collection with the CellGroup objects for columns

      • addColumnGroup

        public void addColumnGroup​(CellGroup grp)
        Adds a CellGroup object for columns to this layout manager. This causes the columns defined by this group object to have the same width (as long as their weight factors are equal).
        Parameters:
        grp - the group object

      • getRowGroups

        public Collection<CellGroup> getRowGroups()
        Returns an unmodifiable collection with the row groups defined for this layout. This collection may be empty, but never null .
        Returns:
        a collection with the CellGroup objects for rows

      • addRowGroup

        public void addRowGroup​(CellGroup grp)
        Adds a CellGroup object for rows to this layout manager. This causes the rows defined by this group object to have the same height (as long as their weight factors are equal).
        Parameters:
        grp - the group object

      • flushCache

        public void flushCache()
        Clears all cached values. Can be called if something has changed at the associated container.

      • removeComponent

        public boolean removeComponent​(Object comp)
        Removes the specified component from this layout.
        Parameters:
        comp - the component to remove
        Returns:
        a flag whether the component was found and could be removed

      • fetchPlatformAdapter

        protected final PercentLayoutPlatformAdapter fetchPlatformAdapter()
        Returns a reference to the associated platform adapter. If no such adapter has been set, an IllegalStateException exception is thrown.
        Returns:
        the platform adapter
        Throws:
        IllegalStateException - if no platform adapter is set

      • getConstraintsBuilder

        public final CellConstraints.Builder getConstraintsBuilder()
        Returns the builder instance for creating CellConstraints objects. Each instance of this class is associated with such a builder. Sub classes or clients can use it for creating their constraints.
        Returns:
        the builder instance for creating CellConstraints objects

      • initDimensions

        protected final void initDimensions​(int cols,
                                    int rows)
        Initializes the dimensions of the table that holds the layout. Constructs the internal arrays with the appropriate sizes and initializes them with default values.
        Parameters:
        cols - the number of columns
        rows - the number of rows

      • getInternalAllColumnConstraints

        protected final CellConstraints[] getInternalAllColumnConstraints()
        Returns the internal array of all cell constraints objects for the layout's column. This method can be used by subclasses for direct read-only access to the layout's column constraints. The public getAllColumnConstraints() method returns a defensive copy of this array. So for performance reasons this method should be used by subclasses.
        Returns:
        the array with the layout's column constraints objects

      • getInternalAllRowConstraints

        protected final CellConstraints[] getInternalAllRowConstraints()
        Returns the internal array of all cell constraints objects for the layout's rows. This method can be used by subclasses for direct read-only access to the layout's row constraints. The public getAllRowConstraints() method returns a defensive copy of this array. So for performance reasons this method should be used by subclasses.
        Returns:
        the array with the layout's row constraints objects

      • getComponent

        protected Object getComponent​(int col,
                              int row)
        Returns the component at the specified position of this layout.
        Parameters:
        col - the column
        row - the row
        Returns:
        the component at this position (null if this cell is not occupied)

      • getPercentData

        protected PercentData getPercentData​(int col,
                                     int row)
        Returns the constraints object for the component at the specified position of this layout.
        Parameters:
        col - the column
        row - the row
        Returns:
        the constraints at this position (null if this cell is not occupied)

      • checkConstraints

        protected PercentData checkConstraints​(Object constraintsObj)
        Checks the specified constraints object. This method ensures that the passed in constraints object is an instance of PercentData and that only valid values for column and row number and the spans are accepted. If invalid values are detected, an IllegalStateException exception is thrown.
        Parameters:
        constraintsObj - the constraints to check
        Returns:
        the percent data object to use
        Throws:
        IllegalStateException - if invalid constraints are detected

      • initCell

        protected void initCell​(Object component,
                        Object constraints)
        Initializes the specified cell in the table-like layout. Information about the component and its associated constraints are stored. This method also checks whether the constrains object is of type PercentData and that its indices and dimensions are valid.
        Parameters:
        component - the component
        constraints - the constraints of this component

      • clearCells

        protected void clearCells()
        Resets the states of all cells in the layout. Uses the current column and row count (which must have been initialized before).

      • clearCells

        protected void clearCells​(int columns,
                          int rows)
        Resets the states of all cells in the layout. After this method was called the layout does not contain any information about components and their constraints.
        Parameters:
        columns - the number of columns
        rows - the number of rows

      • calcSizes

        public int[] calcSizes​(CellConstraints[] constraints,
                       int count,
                       Collection<CellGroup> cellGroups,
                       Object container,
                       int containerSize,
                       boolean vert)
        Calculates the final cell sizes in one direction (horizontal or vertical). This method takes all factors related to sizing into account: the cell constraints, cell groups, weight factors, and the shrinking flag. The resulting array with cell sizes can then be passed to performLayout(Object, int[], int[], int[], int[]).
        Parameters:
        constraints - an array with the constraints for the columns or rows
        count - the number of cells in the opposite dimension (i.e. if columns are calculated, the number of rows and vice versa)
        cellGroups - a collection with the cell groups
        container - the container this layout belongs to
        containerSize - the total size available for the container
        vert - a flag if this calculation is for the X or Y direction
        Returns:
        an array with the cell sizes

      • performLayout

        public void performLayout​(Object container,
                          int[] colSizes,
                          int[] rowSizes,
                          int[] colPos,
                          int[] rowPos)
        Layouts all components that are contained in the associated container. This method determines the positions and sizes of all affected components.
        Parameters:
        container - the container
        colSizes - an array with the sizes of all columns
        rowSizes - an array with the sizes of all rows
        colPos - the start positions of all columns
        rowPos - the start positions of all rows

      • performLayout

        public void performLayout​(Object container,
                          Rectangle insets,
                          Dimension size)
        Layouts all components in the associated container calculating all necessary intermediate sizes and positions. This method calculates the cell sizes and positions and then delegates to the overloaded performLayout() method.
        Parameters:
        container - the container
        insets - a rectangle with the container's insets
        size - the size of the container
        Since:
        1.3

      • calcPreferredLayoutSize

        public Dimension calcPreferredLayoutSize​(Object container)
        Returns the preferred size of this layout. This method applies all cell constraints to determine the optimum size of the layout.
        Parameters:
        container - the associated container object
        Returns:
        the preferred layout size

      • calcMinimumLayoutSize

        public Dimension calcMinimumLayoutSize​(Object container)
        Returns the minimum size of this layout. The behavior of this method depends on the canShrink flag: if this flag is false, it returns the same result as calcPreferredLayoutSize(Object) - because the layout cannot shrink below its preferred size. Otherwise, a size calculation is performed based on the component's minimum size rather than their preferred sizes. Note that this mainly makes a difference if cell constraints are used with the CellSize preferred.
        Parameters:
        container - the associated container object
        Returns:
        the minimum layout size

      • initFromCollections

        protected final void initFromCollections​(Collection<? extends CellConstraints> colConstr,
                                         Collection<? extends CellConstraints> rowConstr)
        Initializes this instance from the given collections with CellConstraints objects.
        Parameters:
        colConstr - a collection with column constraints object
        rowConstr - a collection with row constraints object

      • calcCellSizes

        protected int[] calcCellSizes​(CellConstraints[] constraints,
                              int count,
                              Object container,
                              boolean minimum,
                              boolean vert)
        Calculates the minimum size of either the columns or the rows in the layout. Because of the passed in orientation flag this method can operate on both columns and rows.
        Parameters:
        constraints - an array with the constraints for the columns or rows
        count - the number of cells in the opposite dimension (i.e. if columns are calculated, the number of rows and vice versa)
        container - the container this layout belongs to
        minimum - a flag whether the minimum size should be returned
        vert - a flag if this calculation is for the X or Y direction
        Returns:
        an array with the cell sizes

      • calcComponentSizes

        protected int calcComponentSizes​(CellConstraints constraints,
                                 int index,
                                 int count,
                                 Object container,
                                 boolean minimum,
                                 boolean vert)
        Calculates the size of either a column or a row in the layout. This method iterates over all the components in the actual column or row. Depending on their constraints either their minimum, their preferred or a specified fix size is fetched, and the maximum of these sizes is determined. Only components with a span of 1 are taken into account. With the minimum parameter it is possible to force the method to always return the minimum size. This is required if there is less space available than is required for the preferred width.
        Parameters:
        constraints - the constraints object for the actual column or row
        index - the index of the actual column or row
        count - the number of cells in the opposite dimension
        container - the container this layout belongs to
        minimum - a flag whether the minimum size should be returned
        vert - a flag if this calculation is for the X or Y direction
        Returns:
        the size of the actual column or row

      • handleMultiSpans

        protected void handleMultiSpans​(int[] sizes,
                                CellConstraints[] constraints,
                                List<net.sf.jguiraffe.gui.layout.PercentLayoutBase.CellData> components,
                                Object container,
                                boolean minimum,
                                boolean vert)
        Checks the sizes of components that span multiple cells. For these cells it must be tested whether their size fits into the cell sizes so far calculated. If this is not the case, cells, for which this is possible, must be enlarged.
        Parameters:
        sizes - an array with the so far calculated cell sizes
        constraints - an array with all cell constraints
        components - the list with the multi span components
        container - the container object
        minimum - a flag whether the minimum size should be returned
        vert - the orientation flag

      • calcCellSize

        protected int calcCellSize​(PercentData pd,
                           int colIdx,
                           int rowIdx,
                           Object container,
                           boolean minimum,
                           boolean vert)
        Determines the size of a single cell. Evaluates the constraints of this cell and depending on the size value either the minimum, the preferred or a fixed size is returned.
        Parameters:
        pd - the constraints object
        colIdx - the column index
        rowIdx - the row index
        container - the container this layout belongs to
        minimum - a flag whether the minimum size should be returned
        vert - a flag if this calculation is for the X or Y direction
        Returns:
        the cell's size

      • calcComponentSize

        protected int calcComponentSize​(PercentData pd,
                                Object comp,
                                Object container,
                                boolean minimum,
                                boolean vert)
        Determines the size of a component based on the given constraints object.
        Parameters:
        pd - the constraints object
        comp - the affected component
        container - the container this layout belongs to
        minimum - a flag whether the minimum size should be returned
        vert - a flag if this calculation is for the X or Y direction
        Returns:
        the component's size

      • applyCellGroups

        protected void applyCellGroups​(int[] sizes,
                               Collection<CellGroup> cellGroups)
        Applies the defined cell groups to the so far calculated cell sizes.
        Parameters:
        sizes - an array with the (initial or minimum) cell sizes
        cellGroups - a collection with the defined cell groups

      • calcCellSizesWithGroups

        protected int[] calcCellSizesWithGroups​(CellConstraints[] constraints,
                                        int count,
                                        Collection<CellGroup> cellGroups,
                                        Object container,
                                        boolean minimum,
                                        boolean vert)
        Calculates the sizes of all columns or rows. This is a convenience method, which combines calls to calcCellSizes() and applyCellGroups().
        Parameters:
        constraints - an array with the constraints for the columns or rows
        count - the number of cells in the opposite dimension (i.e. if columns are calculated, the number of rows and vice versa)
        cellGroups - a collection with the defined cell groups
        container - the container this layout belongs to
        minimum - a flag whether the minimum size should be returned
        vert - a flag if this calculation is for the X or Y direction
        Returns:
        an array with the cell sizes
        Throws:
        NullPointerException - if a required parameter is missing

      • calcTotalWeight

        protected int calcTotalWeight​(CellConstraints[] constraints)
        Helper method for calculating the total weight factor.
        Parameters:
        constraints - an array with cell constraints
        Returns:
        the total weight factor

      • getTotalWeightX

        protected int getTotalWeightX()
        Returns the total weight factor for columns.
        Returns:
        the total column weight

      • getTotalWeightY

        protected int getTotalWeightY()
        Returns the total weight factor for rows.
        Returns:
        the total row weight

      • applyWeightFactors

        protected void applyWeightFactors​(int[] sizes,
                                  int containerSize,
                                  CellConstraints[] constraints,
                                  int totalWeight)
        Processes the cells with a weight factor larger than 0. The remaining available space is calculated and divided between the cells with a defined weight factor.
        Parameters:
        sizes - the cell sizes without weight factors
        containerSize - the size of the container (without insets)
        constraints - the cell constraints
        totalWeight - the total weight factor

      • applyWeightFactors

        protected void applyWeightFactors​(int[] sizes,
                                  int containerSize,
                                  boolean vert)
        Processes the cells with a weight factor larger than 0. The remaining available space is calculated and divided between the cells with a defined weight factor.
        Parameters:
        sizes - the cell sizes without weight factors
        containerSize - the size of the container (without insets)
        vert - a flag if this calculation is for the X or Y direction

      • calcCellPositions

        public int[] calcCellPositions​(int[] sizes,
                               int startPos)
        Calculates the start positions of all cells in a column or row.
        Parameters:
        sizes - the cell sizes (must not be null)
        startPos - the start position
        Returns:
        an array with the start positions for all cells
        Throws:
        NullPointerException - if the array with sizes is null

      • alignComponent

        protected void alignComponent​(Rectangle bounds,
                              int colIdx,
                              int rowIdx,
                              int[] sizes,
                              int startPos,
                              int idx,
                              Object container,
                              boolean vert)
        Aligns the specified component.
        Parameters:
        bounds - stores the bounds of the component
        colIdx - the column index
        rowIdx - the row index
        sizes - an array with the sizes of all cells
        startPos - the start position of the actual cell
        idx - the actual cell index
        container - the container this layout belongs to
        vert - a flag if this calculation is for the X or Y direction

      • getOrientationValue

        public static int getOrientationValue​(int v1,
                                      int v2,
                                      boolean vert)
        Helper method for extracting a value from a 2D vector with the specified orientation.
        Parameters:
        v1 - the x value
        v2 - the y value
        vert - the orientation flag (true for the y value, false for the x value)
        Returns:
        the extracted value

      • getMinimumComponentSize

        protected int getMinimumComponentSize​(int col,
                                      int row,
                                      boolean vert)
        Returns the minimum size of the component at the specified column and row position in the given orientation.
        Parameters:
        col - the column index
        row - the row index
        vert - the orientation flag
        Returns:
        the minimum size of the specified component

      • getPreferredComponentSize

        protected int getPreferredComponentSize​(int col,
                                        int row,
                                        boolean vert)
        Returns the preferred size of the component at the specified column and row position in the given orientation.
        Parameters:
        col - the column index
        row - the row index
        vert - the orientation flag
        Returns:
        the minimum size of the specified component

      • setComponentBounds

        protected void setComponentBounds​(int col,
                                  int row,
                                  Rectangle bounds)
        Sets the bounds of the component at the specified column and row position. This method is called after the exact position of this component has been determined by the layout algorithm.
        Parameters:
        col - the column index
        row - the row index
        bounds - the new bounds for this component

      • getSizeHandler

        protected UnitSizeHandler getSizeHandler()
        Returns the currently used size handler implementation.
        Returns:
        the size handler implementation

      • constraintsFor

        protected CellConstraints constraintsFor​(PercentData pd,
                                         boolean vert)
        Returns the constraints object for the specified percent data and the given orientation. If the percent data contains already a constraints object for the given orientation, this object is returned. Otherwise the constraints of the hosting cell (the target cell) are returned.
        Parameters:
        pd - the percent data object
        vert - the orientation flag
        Returns:
        the constraints for this percent data object

      • initCells

        protected abstract void initCells​(PercentLayoutPlatformAdapter adapter)
        Initializes the whole layout. This method is called on first access to the layout information or whenever the layout changes. A concrete sub class must here implement its initialization algorithm, which creates a valid percent layout.
        Parameters:
        adapter - the currently used platform adapter